diff --git a/docs/installation.rst b/docs/installation.rst index dc34638..5d28163 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -6,7 +6,7 @@ Installations Upon installing Docker or Apptainer on your machine, you will be able to use any containerized software listed -in the MolSSI Container Hub. Simply, follow the instructions +in the **MolSSI Container Hub**. Simply, follow the instructions below and navigate to the :ref:`quick_start` page for further instructions on how to unleash the power of containerized software in your research and hopefully, boost your productivity. diff --git a/docs/quick_start.rst b/docs/quick_start.rst index bacde70..9c18e79 100644 --- a/docs/quick_start.rst +++ b/docs/quick_start.rst @@ -10,13 +10,12 @@ Quick Start **This page is under development** -Using **MolSSI-AI Container Hub** is very simple if you are familiar with -`dockerhub `_ know how to use -`Docker `_. - .. Tip:: - - Check the Docker's `documentation `_ + For using **MolSSI-AI Container Hub**, a basic familiarity + with Docker or Apptainer will be helpful but not necessary. + Make sure you take a glance at the :ref:`installation` page. + + Check the Docker `documentation `_ if you are unfamiliar with the Docker. The documentation offers a nice `tutorial `_ series to get you up and running, quickly. @@ -24,5 +23,92 @@ Using **MolSSI-AI Container Hub** is very simple if you are familiar with Structure of MolSSI-AI Container Hub ==================================== -Provide a tree structure and explain what's in one folder, scripts and -Dockerfile. \ No newline at end of file +The **Molssi Container Hub** provides three ingredients for each +containerized software: + +* Image recipie +* Container repository +* Image catalog + +Let's focus on a specific software, say, MOPAC to see how the aforementioned +ingredients come into play. + +In order to be able to use MOPAC, one normally needs to install it on the host +machine first. This can be done either by building MOPAC from the +`source repository `_ or via graphical installer. +One can also use Conda or Fedora package managers or download MOPAC from Google Play Store. +Each route has its complexity and might be suitable for one operating system or another. + +One of the benefits of using Docker or Apptainer is that once you have either of them +on your machine, you are set to use any containerized software including those listed +in the **MolSSI Container Hub** without having to install anything else or try figuring +out and meeting their dependencies. + + +Image Recipes +------------- + +For each containerized software, including MOPAC, we provide an +`image recipe `_ +which tells you how we build the software inside an isolated environment (container). +For simplicity, think of containers as an entity similar to a portable virtualenv or Conda +environment and the image recipe similar to an environment YAML file. Since the software is isolated +in its own filesystem, you can run it on a variety of operating systems in a reproducible manner. + +.. tip:: + + Once you are comfortable with Docker, you can write your own image recipes or fine-tune those + available from the **MolSSI Container Hub** towards your needs. + + +Container Repositories +---------------------- + +Container repository is a place we build and then *register* our ready-to-use containers on. +Container repository is an entity similar to `PyPI `_ which is a +repository for software written in Python: you can search through the repository, find your +software and fetch it into your system to use using a command such as `pip install ...`. +There can be a variety of container repositories within a container registry. +`Docker Hub `_ is an example of a container registry and the +one we use it to publish our containerized software. You can use the following command +to fetch the latest version of MOPAC image into your machine + +.. code-block:: bash + + docker pull molssi/mopac220-mamba141:latest + +Once you have downloaded the image on your machine, you can use it via the following command + +.. code-block:: bash + + docker run --rm -it molssi/mopac220-mamba141:latest /bin/bash + +which creates a temporary Docker container and allows you to get access to it through an interactive +PuTTY bash session. Think of this step as running a ``conda activate `` command. You can now +work with your terminal interactively as if you have MOPAC installed on your system. Just run a +``mopac --version`` command to test it. + +.. note:: + + The ``docker run`` command will use your existing docker image to create the temporary environment + for you. If the image does not exist on your machine, the ``docker run`` command will fetch the + image for you from the repository before running the container. Once you exit from the container + environment, it is automatically destroyed like it never existed! + +.. tip:: + + If you want to retain your environment, you can remove the ``--rm`` flag from your run command. + +Image Catalogs +-------------- + +Image catalogs are auto-generated documentation pages for all information you need about a containerized +software: the developers, the source repository, the links to the container regiestry, image recipes etc. +As an example, you can see in the +`MOPAC catalog `_ that we have also +included the Docker commands that you will need to pull/run the containers from their repository. + +Thus, when you want to use any containerized software listed on the **MolSSI Container Hub**, the fastest +way might be to just go to the `documentation page `_, search for +your favorite containerized software, nativate to its catalog page and copy-paste the Docker command in +a terminal to use the software. \ No newline at end of file diff --git a/molssi_hub/compchem/psi4v180-mamba141/Dockerfile b/molssi_hub/compchem/psi4v180-mamba141/Dockerfile index 62c91f5..a2e46e8 100644 --- a/molssi_hub/compchem/psi4v180-mamba141/Dockerfile +++ b/molssi_hub/compchem/psi4v180-mamba141/Dockerfile @@ -4,7 +4,7 @@ LABEL maintainer="Mohammad Mostafanejad, \ Molecular Sciences Software Institute" RUN mamba install psi4 \ - python=3.8 \ + "pydantic<2.0" \ -c conda-forge/label/libint_dev \ -c conda-forge -yq \ && mamba clean -afy \