Container Usage

OCDocker includes Docker, Podman, and Singularity/Apptainer helpers. Containers are useful when you want a reproducible runtime, but host data paths still need to be mounted explicitly or kept under a mounted workspace.

Docker

Install the short ocd wrapper:

containers/docker/install_docker.sh --install-ocd

Default backend is PostgreSQL. Set a database password before using the wrapper:

export OCDOCKER_DB_PASS='<db_password>'
ocd doctor

Use MySQL instead:

export OCDOCKER_DB_BACKEND=mysql
export OCDOCKER_DB_PASS='<db_password>'
export MYSQL_ROOT_PASSWORD='<root_password>'
ocd doctor

The wrapper auto-mounts likely host paths from CLI arguments. You can also mount paths explicitly:

ocd --mount /data/project pipeline \
  --receptor /data/project/receptor.pdb \
  --ligand /data/project/ligand.sdf \
  --box /data/project/box.pdb \
  --outdir /data/project/output

Recommended pattern: keep all inputs and outputs under one project directory and mount that directory once.

Docker database behavior

The committed Docker config files do not contain a real password. The entrypoint creates a runtime config in /tmp/ocdocker/OCDocker.cfg using the environment values passed to compose.

Relevant variables:

  • OCDOCKER_DB_BACKEND: postgresql or mysql.

  • OCDOCKER_DB_PASS: required for Docker database services.

  • MYSQL_ROOT_PASSWORD: required when using the MySQL service.

  • OCDOCKER_DATABASE: defaults to ocdocker.

  • OCDOCKER_OPTIMIZEDB: defaults to optimization.

  • OCDOCKER_DB_USER: defaults to ocdocker.

Singularity/Apptainer

Wrapper:

containers/singularity/ocdocker.sh --help

Sidecar database helpers:

containers/singularity/postgresql.sh start
containers/singularity/mysql.sh start

Useful options:

  • --cfg-source /path/to/OCDocker.cfg: parse config for bind hints.

  • --dry-run: print the resolved command without executing it.

  • --workdir /path/to/project: run from a mounted project directory.

Example:

export OCDOCKER_SINGULARITY_IMAGE=/path/to/ocdocker.sif
containers/singularity/ocdocker.sh \
  --workdir /data/project \
  script --allow-unsafe-exec /data/project/run.py

Scheduler workflows

For workflow managers, prefer explicit resources and stable output markers:

ocdocker \
  --threads 4 \
  --tmp-dir tmp/sample_001 \
  pipeline \
  --receptor input/sample_001/receptor.pdbqt \
  --ligand input/sample_001/ligand.pdbqt \
  --box input/sample_001/box.txt \
  --outdir results/sample_001 \
  --engines vina,smina,plants \
  --strict-engines \
  --done-marker results/sample_001/done.json \
  --log-file logs/sample_001.log \
  --no-stdout-log

Examples:

  • examples/19_Snakefile_ocdocker_pipeline.smk

  • examples/20_Snakefile_ocdocker_granular_pipeline.smk