add Singularity recipe with doc

As soon as docker image is on external docker registry, the documentation
for the singularity container must be updated

container/Singularity

+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
+

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)

doc/container/CMakeLists.txt

+set(CONTAINER_RST
+  index.rst
+  docker.rst
+  singularity.rst
+)
+
+add_doc_source(NAME container RST ${CONTAINER_RST})

doc/container.rst → doc/container/docker.rst

-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
   

doc/container/index.rst

+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>
+
+
+
+
+
+

doc/container/singularity.rst

+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`. 

doc/users.rst

@@ -12,7 +12,7 @@ Contents:
    gettingstarted
    actions/index
    buildsystem
-   container
+   container/index
    modelling/index
    sidechain/index
    scoring/index