Docker and Apptainer for Bioinformatics

A container can make a bioinformatics tool's software environment easier to reuse, but it does not package your reads, reference genome, scheduler policy, or every host dependency. This walkthrough traces file paths in a local Docker BWA-MEM example and an optional Apptainer/Slurm script, with attention to the files each command can actually see.

What the container freezes, and what it does not

An image bundles an application and its userspace dependencies. That is useful when tools require conflicting libraries or when you need to preserve an environment, but it does not guarantee identical results across all hosts: kernel and hardware behavior, environment variables, mounted files, command-line parameters, and external services can still matter. Record the exact image reference (prefer a digest for durable identification), input checksums, tool arguments, and relevant host/runtime details. A tag can be moved, and a container is not a substitute for workflow provenance or biological validation.

Docker commonly runs through a privileged daemon, which is why shared clusters often restrict Docker. Apptainer (formerly Singularity) is designed for unprivileged HPC use, but installation, configuration, allowed registries, and bind paths remain site-specific. Follow your cluster's documentation rather than assuming Docker is universally unavailable or that Apptainer is installed.

Prepare a small, explicit project layout

For a reproducible smoke test, create the fixture below in a new project directory. It is invented sequence data for checking file flow only, not a biological sample or a test of BWA's suitability for any assay. The commands require Bash, Docker with permission to access its daemon, and host BWA for indexing. Check availability before starting:

command -v docker && docker --version
command -v bwa && bwa 2>&1 | head -n 3

If either executable is missing, stop here and install it using the official instructions for your operating system or ask your administrator; do not proceed with an incomplete project. Record the version output in your notes. Then create the two small inputs (the reads are exact substrings of the synthetic reference):

mkdir -p bwa-container-lab/results
cd bwa-container-lab
cat > reference.fa <<'EOF'
>synthetic_reference
ACGTTGCAAGTCCTAGGATCCGATGCTAACGTAGCTTAGGCTAACCGT
EOF
cat > reads.fq <<'EOF'
@synthetic_read_1
ACGTTGCAAGTCCTAGGATC
+
IIIIIIIIIIIIIIIIIIII
@synthetic_read_2
GATGCTAACGTAGCTTAGGCT
+
IIIIIIIIIIIIIIIIIIIII
EOF
wc -l reference.fa reads.fq

The final command should report 2 lines for the FASTA and 8 for FASTQ. If it does not, check that the quoted heredoc terminators were copied on their own lines. Now build the BWA index in this directory; the index files must remain beside the FASTA:

bwa index reference.fa

BWA writes index sidecar files beside the reference. Keep them with the FASTA and make the directory available inside the container. BWA-MEM accepts a reference and one or two FASTQ read files; this single-read example is illustrative, not an assessment of paired-end data, read quality, or mapping suitability.

Run the tool locally with Docker

Confirm the Docker daemon is reachable with docker info; if this fails, stop and resolve host permissions or daemon availability before attempting a pull. Verify the image tag with its registry documentation, then run from the project directory. The example mounts that directory read-write at /work, so input and generated files are visible across the boundary:

IMAGE='quay.io/biocontainers/bwa:0.7.17--hed695b0_7'  # verify this tag in the registry
mkdir -p results
docker run --rm \
  --mount "type=bind,src=$PWD,dst=/work" \
  --workdir /work \
  "$IMAGE" bwa mem -t 4 reference.fa reads.fq \
  > results/reads.sam

The redirection is performed by the host shell, not inside Docker; because the working directory is mounted, the SAM file lands in the host's results/ directory. The command assumes the image can start bwa with this invocation and the tag exists and is accessible. Check the registry and image documentation before relying on either assumption. If the source directory is missing, Docker's explicit --mount form errors rather than silently creating it; check the mount path and permissions. Mounting a project read-write allows container processes to alter its contents. Use a read-only input mount plus a separate writable output directory when the tool and directory layout permit.

File-flow check, no Docker required: In this example, $PWD is the host project directory and it is mounted at /work inside the container. The program reads reference.fa and reads.fq at /work; where does results/reads.sam go? The host shell handles > results/reads.sam, so it writes in the host project directory, under results/. The bind mount makes that same project directory visible to the container.

Use the same image on a Slurm cluster

This section is optional and applies only if you have an authorized Slurm account on a cluster that provides Apptainer (or its locally supported Singularity command). Check the site documentation for resource limits, permitted image acquisition, storage paths, and submission procedures; do not install software or submit jobs on a shared system without authorization. Where permitted, pull the OCI image once (often on a login or transfer node). This converts the registry image into a local SIF file; network access, image caching, and where pulls are allowed are cluster-specific.

apptainer pull bwa.sif docker://quay.io/biocontainers/bwa:0.7.17--hed695b0_7

Save the following as a Slurm job script in the project directory and submit it using your site's procedure. It explicitly binds the current project to /work; the inputs and output path then refer to files the container can access.

#!/bin/bash
#SBATCH --job-name=bwa_map
#SBATCH --cpus-per-task=4
#SBATCH --mem=8G
#SBATCH --time=01:00:00

set -euo pipefail
mkdir -p results
apptainer exec --bind "$PWD:/work" --pwd /work bwa.sif \
  bwa mem -t "$SLURM_CPUS_PER_TASK" reference.fa reads.fq \
  > results/reads.sam

Resource values are examples, not recommendations; adjust them to the input size, cluster policy, and measured workload. The output redirection occurs in the job shell on the host filesystem. If a cluster uses the singularity executable rather than apptainer, or restricts pulls/binds, adapt the command according to local documentation. A failed pull can reflect network or registry policy; a file-not-found error inside the job commonly points to a missing bind, wrong working directory, or absent input. Also verify write permissions on results/ and inspect the scheduler's standard output/error files.

Check the result and preserve provenance

• Confirm the job exited successfully and that results/reads.sam exists and is non-empty. With the two synthetic reads, inspect for a SAM header and alignment records corresponding to the two input reads; exact flags and formatting are tool-version dependent. A non-empty file or matching record count checks only this smoke test, not alignment quality.
• Record the immutable image digest where available (for Docker, inspect the pulled image with docker image inspect --format '{{json .RepoDigests}}' "$IMAGE"; an empty list means no RepoDigest was recorded), the BWA version reported by the image, reference and read checksums, index-generation command, full mapping command, and scheduler/runtime versions. Capture runtime versions with docker --version, apptainer --version (or the site-supported singularity --version), and sinfo --version where available. These commands provide provenance; they are not versions tested or certified by this page.
• Review the SAM header and representative records, then use a suitable downstream QC workflow to evaluate mapping rate, flags, and sample-specific expectations. No universal mapping-rate threshold or biological conclusion follows from container success.
• For a reproducible pipeline, version the job/workflow definition and retain immutable image identifiers. Rebuilding a Dockerfile later can change if base images or package repositories are not pinned; pinning tool packages alone does not freeze every dependency.

Choosing between Docker and Apptainer

Use Docker where you control the host and its daemon is permitted; use Apptainer on an HPC system that supports it and documents the necessary execution policy. Both can run OCI-origin images, but runtime configuration, bind defaults, environment handling, and supported options are not identical. A successful run in one environment is not proof that another will behave identically. Workflow managers such as Nextflow can coordinate containers, but their runtime flags and configuration vary by version; consult the workflow manager's current documentation rather than assuming a particular flag is interchangeable.