diff --git a/container/Singularity b/container/Singularity
new file mode 100644
index 0000000000000000000000000000000000000000..7fb04357d405209c1b3251b15542344e9ffa4ae2
--- /dev/null
+++ b/container/Singularity
@@ -0,0 +1,116 @@
+BootStrap: docker
+Registry: http://localhost:5000
+Namespace:
+From: promod:latest
+
+%post
+##############################################################################
+# POST
+##############################################################################
+
+# CHANGE DASH TO BASH
+rm /bin/sh
+ln -sf /bin/bash /bin/sh
+
+# INSTALL NGL AND JUPYTER WITH PIP
+######################################
+pip install --no-cache-dir nglview==1.1.6 \
+ jupyter==1.0.0
+
+# SETUP JUPYTER
+###############
+mkdir -p /usr/local/share/ipython
+mkdir -p /usr/local/share/jupyter
+mkdir -p /usr/local/etc/jupyter
+mkdir -p /usr/local/share/jupyter/runtime
+mkdir -p /usr/local/share/jupyter/kernels/ost-kernel
+chmod a+rw -R /usr/local/share/ipython
+chmod a+rw -R /usr/local/share/jupyter
+chmod a+rw -R /usr/local/etc/jupyter
+chmod a+rw -R /usr/local/share/jupyter/runtime
+cat > /usr/local/share/jupyter/kernels/ost-kernel/kernel.json <<EOF
+{
+ "display_name": "OST",
+ "language": "python",
+ "argv": [
+ "python",
+ "-m", "ipykernel",
+ "-f", "{connection_file}",
+ "--InteractiveShellApp.exec_PYTHONSTARTUP=False",
+ "--InteractiveShellApp.exec_files=['/usr/local/lib64/python2.7/site-packages/ost/ost_startup.py']"
+ ],
+ "env": {
+ }
+}
+EOF
+
+jupyter nbextension enable nglview --py --sys-prefix
+
+%environment
+##############################################################################
+# ENVIRONMENT
+##############################################################################
+export QT_X11_NO_MITSHM=1
+export IPYTHONDIR=/usr/local/share/ipython
+export JUPYTER_CONFIG_DIR=/usr/local/etc/jupyter
+export JUPYTER_PATH=/usr/local/share/jupyter
+export JUPYTER_RUNTIME_DIR=$JUPYTER_PATH/runtime
+
+%apprun Notebook
+##############################################################################
+# NOTEBOOK APP
+##############################################################################
+jupyter notebook --NotebookApp.iopub_data_rate_limit=10000000 --no-browser "$@"
+
+%apphelp Notebook
+A Jupyter notebook playground with OST ProMod3 and nglview.
+
+Usage:
+
+ singularity run --app Notebook <IMAGE> [options]
+
+The Jupyter notebook is run by default with `--NotebookApp.iopub_data_rate_limit=10000000`
+and `--no-browser` options.
+
+Useful options when running on remote server:
+ --ip=<Unicode> (NotebookApp.ip)
+ Default: 'localhost'
+ The IP address the notebook server will listen on.
+ --port=<Integer> (NotebookApp.port)
+ Default: 8888
+ The port the notebook server will listen on.
+
+Copy the URL to the browser and launch the notebook with OST kernel. This will
+load all necessary OST components just like in the OST shell.
+ProMod3 modules can be imported as needed. We also enabled
+the nglview widget to interactively view molecular structures and trajectories.
+For more details on how to use nglview see http://nglviewer.org/nglview/latest/.
+
+As the Singularity mounts $HOME by default, Jupyter and Ipython config files
+are moved to separate directories. Proper environmental variables are also set.
+
+To list of all available options:
+
+ singularity run --app Notebook <IMAGE> --help
+
+%runscript
+##############################################################################
+# RUNSCRIPT
+##############################################################################
+cat << EOF
+Singularity container for OST $OPENSTRUCTURE_VERSION and ProMod3 $PROMOD_VERSION
+
+This container can run the ost, pm or chemdict_tool executables.
+For convenience, a jupyter notebook playground with OST, ProMod3 and nglview is
+available.
+
+To run ost, pm or chemdict_tool executables, use the exec command.
+E.g. to run scripts with pm:
+
+singularity exec <IMAGE> pm my_script.py [options]
+
+To get more information on how to run the Notebook run:
+
+singularity help --app Notebook <IMAGE NAME>
+EOF
+
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index c3c0ce06aec1fceacafd9605e966a6de04d69849..31cd10f60f6962ced36e1e204f76a8ed226713ea 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -16,9 +16,10 @@ gettingstarted.rst
portableIO.rst
references.rst
licence.rst
-container.rst
)
+add_subdirectory(container)
+
# add documentation tests (must be done before rest below!)
add_custom_target(doctest)
add_subdirectory(tests)
diff --git a/doc/container/CMakeLists.txt b/doc/container/CMakeLists.txt
new file mode 100644
index 0000000000000000000000000000000000000000..35219690fafc72ce0d4509a035533d25a9965186
--- /dev/null
+++ b/doc/container/CMakeLists.txt
@@ -0,0 +1,7 @@
+set(CONTAINER_RST
+ index.rst
+ docker.rst
+ singularity.rst
+)
+
+add_doc_source(NAME container RST ${CONTAINER_RST})
diff --git a/doc/container.rst b/doc/container/docker.rst
similarity index 66%
rename from doc/container.rst
rename to doc/container/docker.rst
index 85625eb21e20bcc521a4d271ae114284dd9dff45..57cc2ab1d61ed32c98c9768516a60e17d994a34e 100644
--- a/doc/container.rst
+++ b/doc/container/docker.rst
@@ -1,53 +1,46 @@
-ProMod3 and Containers
-======================
-
-
-ProMod3 offers build recipes for Docker and Singularity in
-<PATH_TO_PROMOD3_CHECKOUT>/container. To avoid code duplication,
-the Singularity container bootstraps from the Docker one and adds
-some sugar on top.
-
Docker
-------
+======
-Build image
------------
+Build Docker Image
+------------------
In order to build the image:
.. code-block:: bash
- docker build --tag <IMAGE_NAME> -f Dockerfile <PATH TO DOCKERFILE DIR>
+ sudo docker build --tag <IMAGE_NAME> -f Dockerfile <PATH_TO_DOCKERFILE_DIR>
You can chose any image name (tag) eg. promod.
-Run script and actions with OST/PM
-----------------------------------
+Run scripts and actions with OST/PM
+-----------------------------------
If script or action requires some external files eg. PDBs, they have to be located in the
path accessible via mounted volume and should be accessed via docker (NOT LOCAL)
-path. Eg. assuming that we have a struc.pdb file in /home/user/pdbs directory and
-a script.py in /home/user we could mount the /home/user to /home in docker as
-above by specifying -v /home/user:/home. To run the script we thus need to
+path. Eg. assuming that we have a struc.pdb file in /home/<USER>/pdbs directory and
+a script.py in /home/<USER> we could mount the /home/<USER> to /home in docker as
+above by specifying -v /home/<USER>:/home. To run the script we thus need to
provide the (relative) path to the script and (relative) path to the file eg:
.. code-block:: bash
- docker run --rm -v /home/<USER>:/home <IMAGE_NAME> pm script.py pdbs/struct.pdb
+ sudo docker run --rm -v /home/<USER>:/home <IMAGE_NAME> pm script.py pdbs/struct.pdb
or with absolute paths:
.. code-block:: bash
- docker run --rm -v /home/<USER>:/home <IMAGE_NAME> pm /home/script.py /home/pdbs/struct.pdb
+ sudo docker run --rm -v /home/<USER>:/home <IMAGE_NAME> pm /home/script.py /home/pdbs/struct.pdb
An alternative is to mount the current working directory into the docker home:
.. code-block:: bash
- docker run --rm -v $(pwd):/home <IMAGE_NAME> pm script.py pdbs/struct.pdb
+ sudo docker run --rm -v $(pwd):/home <IMAGE_NAME> pm script.py pdbs/struct.pdb
+
+.. _docker_compound_lib:
The Compound Library
--------------------
@@ -68,8 +61,8 @@ The suggested way of doing this is to generate your own compound library and
mount it into the container where the original compound lib resides to
override it.
-The simplest way to create compound library is to use the
-:program:`chemdict_tool` available in the container. The programs allows you
+The simplest way to create a compound library is to use the
+:program:`chemdict_tool` available in the container. The program allows you
to import the chemical description of the compounds from a MMCIF dictionary,
e.g. the components.cif dictionary provided by the PDB.
The latest dictionary can be downloaded from the
@@ -82,16 +75,17 @@ convert the MMCIF dictionary into our internal format:
.. code-block:: bash
- docker run --rm -v $(pwd):/home <IMAGE_NAME> chemdict_tool create components.cif compounds.chemlib
+ sudo docker run --rm -v $(pwd):/home <IMAGE_NAME> chemdict_tool create components.cif.gz compounds.chemlib
-To run a script with the upated compound library, use the -v option for overriding:
+To run a script with the upated compound library, use the -v option for mounting/overriding:
.. code-block:: bash
- docker run --rm -v /home/user:/home -v <COMPLIB_DIR_LOCALHOST>:<COMPLIB_DIR_CONTAINER> <IMAGE_NAME> script.py pdbs/struct.pdb
+ sudo docker run --rm -v /home/<USER>:/home -v <COMPLIB_DIR_LOCALHOST>:<COMPLIB_DIR_CONTAINER> <IMAGE_NAME> pm script.py pdbs/struct.pdb
with COMPLIB_DIR_LOCALHOST being the directory that contains the newly generated
-compound library and COMPLIB_DIR_CONTAINER the according path in the container.
+compound library with name compounds.chemlib and COMPLIB_DIR_CONTAINER the
+according path in the container.
If you didnt change anything in the Dockerfile, the latter should be
/usr/local/share/ost_complib
diff --git a/doc/container/index.rst b/doc/container/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9fac38710ca915c70ec599d2018f697740c2c018
--- /dev/null
+++ b/doc/container/index.rst
@@ -0,0 +1,20 @@
+ProMod3 and Containers
+======================
+
+
+ProMod3 offers build recipes for Docker and Singularity in
+<PATH_TO_PROMOD3_CHECKOUT>/container. To avoid code duplication,
+the Singularity container bootstraps from the Docker one and adds
+some sugar on top.
+
+.. toctree::
+ :maxdepth: 1
+
+ Docker <docker>
+ Singularity <singularity>
+
+
+
+
+
+
diff --git a/doc/container/singularity.rst b/doc/container/singularity.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7b4bb4dd4e997d404509c32ccf5c21860cb9a4ca
--- /dev/null
+++ b/doc/container/singularity.rst
@@ -0,0 +1,104 @@
+Singularity
+===========
+
+We do not provide a "standalone" Singularity image, but rather bootstrap from a
+Docker image.
+
+Build Singularity Image
+-----------------------
+
+You can pull the Docker image to start with from two different sources.
+
+Option One:
+
+You built the Docker image locally and want to use it as a starting point. For
+this we have to fire up a local Docker registry and pull from there. Let's
+assume you built the Docker image with tag promod.
+
+Fire the local Registry and push the promod image to it:
+
+.. code-block:: bash
+
+ sudo docker run -d -p 5000:5000 --restart=always --name registry registry:2
+ sudo docker tag promod localhost:5000/promod
+ sudo docker push localhost:5000/promod
+
+Make sure, that on top of your Singularity recipe you have something like:
+
+.. code-block:: bash
+
+ BootStrap: docker
+ Registry: http://localhost:5000
+ Namespace:
+ From: promod:latest
+
+and build the image with:
+
+.. code-block:: bash
+
+ sudo SINGULARITY_NOHTTPS=1 singularity build promod.img Singularity
+
+
+Option Two:
+
+You pull a Docker image from an external Docker registry.
+Fill in a lot of words as soon as its on Dockerhub. Many words. The best words.
+
+and build the image with:
+
+.. code-block:: bash
+
+ sudo singularity build promod.img Singularity
+
+
+Run scripts and actions with OST/PM
+-----------------------------------
+
+The created container can run the ost, pm or chemdict_tool executables.
+For convenience, a jupyter notebook playground with OST, ProMod3 and nglview is
+available.
+
+To run ost, pm or chemdict_tool executables, use the exec command.
+E.g. to run scripts with pm:
+
+.. code-block:: bash
+
+ singularity exec <IMAGE> pm my_script.py [options]
+
+The jupyter notebook is setup as an app in the container.
+To get help on how to run it:
+
+.. code-block:: bash
+
+ singularity run --app Notebook <IMAGE> --help
+
+
+The Compound Library
+--------------------
+
+You'll have the exact same problem with outdated compound libraries as in the
+raw Docker image. You can find more information on that matter in the Docker
+section of the documentation: :ref:`docker_compound_lib`.
+
+The same trick of mounting an up to date compound library from the local host into
+the container applies. The two relevant commands for Singularity are building
+a new library and mount it.
+
+Build a new library:
+
+.. code-block:: bash
+
+ singularity exec <IMAGE_NAME> chemdict_tool create components.cif.gz compounds.chemlib
+
+Run some script with an updated compound library from localhost:
+
+.. code-block:: bash
+
+ singularity exec -B <COMPLIB_DIR_LOCALHOST>:<COMPLIB_DIR_CONTAINER> <IMAGE_NAME> pm my_script.py
+
+Same as for the Docker, if you didn't meddle with the original Dockerfile,
+<COMPLIB_DIR_CONTAINER> should be /usr/local/share/ost_complib.
+<COMPLIB_DIR_LOCALHOST> is the directory that contains the compound lib with the
+name compounds.chemlib that you created before. Make sure that everything works
+as expected by executing the exact same lines of Python code as described
+in the Docker documentation: :ref:`docker_compound_lib`.
diff --git a/doc/users.rst b/doc/users.rst
index 8ee83f28c19e20da7225afd064af2a4d198fd424..893af45f801380c0f846fa328fc518a4caeaacb5 100644
--- a/doc/users.rst
+++ b/doc/users.rst
@@ -12,7 +12,7 @@ Contents:
gettingstarted
actions/index
buildsystem
- container
+ container/index
modelling/index
sidechain/index
scoring/index