From 93a07657a85f2c159930ee2fb9ff776c62694c72 Mon Sep 17 00:00:00 2001
From: Mike Lin <dna@mlin.net>
Date: Sat, 27 Nov 2021 15:20:05 -1000
Subject: [PATCH] docs for singularity & podman

---
 docs/conf.py            |  2 +-
 docs/index.rst          |  1 +
 docs/runner_backends.md | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 docs/runner_backends.md

diff --git a/docs/conf.py b/docs/conf.py
index 44fd9105..23274649 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,7 +20,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'miniwdl'
-copyright = '2019, CZI'
+copyright = '2019-2022, CZI'
 author = 'CZI'
 
 # The short X.Y version
diff --git a/docs/index.rst b/docs/index.rst
index a02ad6c3..6fe51fb9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,7 @@ the bioinformatics-focused `Workflow Description Language (WDL) <http://openwdl.
    runner_cli.rst
    runner_reference.md
    runner_advanced.md
+   runner_backends.md
    check.md
    FAQ.md
    WDL.rst
diff --git a/docs/runner_backends.md b/docs/runner_backends.md
new file mode 100644
index 00000000..2545704f
--- /dev/null
+++ b/docs/runner_backends.md
@@ -0,0 +1,36 @@
+# `miniwdl run` container runtimes
+
+miniwdl's default Docker task runtime is recommended for production use. Users unable to employ the Docker daemon may configure miniwdl to use [Singularity](https://sylabs.io/singularity/) or [Podman](https://podman.io/) instead (locally on Linux hosts only).
+
+## Singularity (BETA)
+
+Once a system administrator [installs Singularity](https://sylabs.io/guides/master/admin-guide/installation.html), it's usually operated without root privileges. To configure miniwdl to use Singularity instead of Docker:
+
+1. Run the following command to sanity-check Singularity: `singularity run --fakeroot docker://ubuntu:20.04 cat /etc/issue`
+2. Set the environment variable `MINIWDL__SCHEDULER__CONTAINER_BACKEND=singularity` or the equivalent [configuration file](https://miniwdl.readthedocs.io/en/latest/runner_reference.html#configuration) option `[scheduler] container_backend=singularity`
+3. Test the configuration with `miniwdl run_self_test`
+
+Limitations:
+
+* Inside a Singularity container, only the working directory and /tmp are writable, while the rest of the file system is read-only. Task commands that attempt to write elsewhere (e.g. installing software/libraries at runtime) will fail.
+* Tasks' `runtime.docker` declarations are used as Docker (OCI) image tags with [Singularity's Docker image import features](https://sylabs.io/guides/2.6/user-guide/singularity_and_docker.html); SIF image files cannot yet be used directly.
+* Task containers aren't actually restricted to use only their declared `runtime.cpu` and `runtime.memory` resources once they start, although those reservations are considered for parallel scheduling.
+  * If parallel container scheduling causes problems, then it can be disabled (serializing the workflow) by setting the environment variable `MINIWDL__SCHEDULER__CALL_CONCURRENCY=1` or the equivalent configuration file option `[scheduler] call_concurrency=1`.
+* Unlike with the Docker daemon, separate `miniwdl run` processes using the Singularity runtime don't coordinate their CPU/memory reservations for container scheduling. Running multiple resource-intensive workflows concurrently (with separate `miniwdl run` invocations) is liable to overload the host.
+
+## Podman (BETA)
+
+Podman closely resembles Docker, to the extent that it's usually operated as root. If miniwdl is configured to use Podman (and isn't running as root itself), then it attempts to use `sudo podman` internally, which therefore must not require interactive password entry.
+
+To configure miniwdl to use Podman instead of Docker:
+
+1. Allow relevant user(s) to `sudo podman` without password entry using [this procedure](https://minikube.sigs.k8s.io/docs/drivers/podman/#known-issues).
+2. Run the following command to sanity-check Podman: `sudo podman run ubuntu:20.04 cat /etc/issue`
+3. Set the environment variable `MINIWDL__SCHEDULER__CONTAINER_BACKEND=podman` or the equivalent [configuration file](https://miniwdl.readthedocs.io/en/latest/runner_reference.html#configuration) option `[scheduler] container_backend=podman`
+4. Test the configuration with `miniwdl run_self_test`
+
+Limitations:
+
+* Without the aforementioned procedure to enable passwordless `sudo podman`, typical defaults require password entry after a five-minute timeout since the last `sudo` operation. This can cause confusion when test runs succeed because they turn over containers rapidly, but lengthy workflows fail in the middle due to this timeout.
+  * Alternatives to the passwordless configuration include [increasing the timeout](https://unix.stackexchange.com/questions/382060/change-default-sudo-password-timeout), using a background script to [refresh it temporarily](https://serverfault.com/a/702019), or running miniwdl itself as root.
+* Unlike with the Docker daemon, separate `miniwdl run` processes using the Podman runtime don't coordinate their CPU/memory reservations for container scheduling. Running multiple resource-intensive workflows concurrently (with separate `miniwdl run` invocations) is liable to overload the host.