Add Docker documentation and installation note for containerized setup

Author: calvinp0

docs/source/docker.rst

@@ -0,0 +1,71 @@
+.. _docker:
+
+Docker image
+============
+
+The published Docker image includes ARC and RMG along with convenience entrypoints.
+Bind-mount your working directory and pass an input file path that exists inside
+the container. For best write access on bind mounts, pass your host UID/GID as
+``PUID``/``PGID`` (the entrypoint remaps the ``mambauser`` account).
+
+Run ARC non-interactively::
+
+    docker run --rm \
+        -v "$PWD:/work" -w /work \
+        -e PUID=$(id -u) -e PGID=$(id -g) \
+        laxzal/arc:latest arc my_case/input.yml
+
+Run RMG non-interactively::
+
+    docker run --rm \
+        -v "$PWD:/work" -w /work \
+        -e PUID=$(id -u) -e PGID=$(id -g) \
+        laxzal/arc:latest rmg my_case/input.py
+
+Manual RMG invocation::
+
+    docker run --rm \
+        -v "$PWD:/work" -w /work \
+        -e PUID=$(id -u) -e PGID=$(id -g) \
+        laxzal/arc:latest \
+        micromamba run -n rmg_env python /home/mambauser/Code/RMG-Py/rmg.py my_case/input.py
+
+Manual ARC invocation::
+
+    docker run --rm \
+        -v "$PWD:/work" -w /work \
+        -e PUID=$(id -u) -e PGID=$(id -g) \
+        laxzal/arc:latest \
+        micromamba run -n arc_env python /home/mambauser/Code/ARC/ARC.py my_case/input.yml
+
+Open an interactive shell::
+
+    docker run --rm -it \
+        -v "$PWD:/work" -w /work \
+        -e PUID=$(id -u) -e PGID=$(id -g) \
+        laxzal/arc:latest
+
+For job submission, the scheduler client tools must be available in the container
+or accessed via SSH on a remote host.
+
+Aliases in interactive shells
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you open an interactive shell, the image provides these aliases::
+
+    rc              # reload ~/.bashrc
+    rce, erc        # edit ~/.bashrc with nano
+
+    mamba, conda    # micromamba
+    deact           # micromamba deactivate
+
+    rmge, arce      # activate rmg_env / arc_env
+
+    rmgcode         # cd to /home/mambauser/Code/RMG-Py
+    dbcode          # cd to /home/mambauser/Code/RMG-database
+    arcode          # cd to /home/mambauser/Code/ARC
+
+    rmg             # run RMG with input.py, tee logs
+    arkane          # run Arkane with input.py, tee logs
+    arc             # run ARC with input.yml, tee logs
+    arcrestart      # run ARC with restart.yml, tee logs

docs/source/index.rst

@@ -35,6 +35,7 @@ Documentation Contents
    :maxdepth: 2
 
    installation
+   docker
    running
    examples
    advanced

docs/source/installation.rst

@@ -11,6 +11,9 @@ Note:
     ARC was only tested on Linux (Ubuntu_ 18.04.1 and 20.04 LTS) and Mac machines.
     We don't expect it to work smoothly on Windows machines.
 
+Note:
+    For a containerized setup, see the :ref:`Docker image <docker>` documentation.
+
 Note:
     These installation instructions assume you already have access to a server with a cluster scheduling software
     (ARC currently supports SGE, Slurm, PBS, and HTCondor) and with properly installed electronic structure software