Containerized Installation with Apptainer or Singularity

Apptainer is the recommended installation for HPC systems. It runs an immutable image without a Docker daemon and binds cluster filesystems directly into interactive sessions and scheduler jobs.

The image does not contain MongoDB or the large annotation databases. Store reference data once on shared high-throughput storage.

Requirements

• Linux on amd64 or arm64;
• Apptainer or Singularity, commonly supplied as an environment module;
• project storage for the SIF, cache, annotation bundle, intermediates, and BFF output;
• scheduler memory sized above the configured Java heap.

1. Load the Runtime

module load apptainer
apptainer --version

Use singularity in place of apptainer on clusters that retain the older command name.

2. Pull the Image

Put cache and temporary files on project storage rather than a small home directory:

export APPTAINER_CACHEDIR=/path/to/project/cache
export APPTAINER_TMPDIR=/path/to/project/tmp

apptainer pull beacon2-cbi-tools.sif \
  docker://manuelrueda/beacon2-cbi-tools:latest

For reproducible work, record the application version and SIF checksum:

apptainer exec beacon2-cbi-tools.sif bff-tools --version
sha256sum beacon2-cbi-tools.sif

3. Validate Metadata

apptainer exec \
  --bind "$PWD:/work" \
  beacon2-cbi-tools.sif \
  bff-tools validate -i /work/metadata.xlsx -o /work/bff

Apptainer runs with the invoking user's identity, so output files retain normal cluster ownership.

4. Prepare Annotation Data

Raw VCF and SNP-array input requires the external annotation bundle. Select a persistent shared directory and run the image installer on a login or data-transfer node:

export BFF_TOOLS_DATA=/shared/beacon2-cbi-tools-data
mkdir -p "$BFF_TOOLS_DATA"
apptainer exec \
  --bind "$BFF_TOOLS_DATA:/bundle" \
  beacon2-cbi-tools.sif \
  bff-tools install-resources --data-dir /bundle

Use install-resources --print-links when automated Google Drive access is unavailable. Full storage and recovery guidance is in Annotation Data. The commands below bind the extracted host directory to the portable in-container default.

5. Annotate and Convert a Raw VCF

apptainer exec \
  --bind "$PWD:/work" \
  --bind "$BFF_TOOLS_DATA:/beacon2-cbi-tools-data" \
  --env BFF_TOOLS_DATA=/beacon2-cbi-tools-data \
  beacon2-cbi-tools.sif \
  bff-tools vcf -i /work/cohort.vcf.gz \
  --genome hg38 \
  --dataset-id cohort-1 \
  -o /work/cohort-bff

Annotation is enabled by default. Use --no-annotate only for VCF input that already has a compatible SnpEff ANN header and record annotations.

6. Bind Writable Scratch Space

Java annotation and compressed intermediates can be large. If /tmp is restricted, configure tmpdir and bind a scheduler-local or project scratch directory:

mkdir -p /path/to/project/bff-tmp

apptainer exec \
  --bind "$PWD:/work" \
  --bind "$BFF_TOOLS_DATA:/beacon2-cbi-tools-data" \
  --env BFF_TOOLS_DATA=/beacon2-cbi-tools-data \
  --bind "/path/to/project/bff-tmp:/bff-tmp" \
  beacon2-cbi-tools.sif \
  bff-tools vcf -i /work/cohort.vcf.gz \
  --genome hg38 -c /work/config.yaml -o /work/cohort-bff

Set tmpdir: /bff-tmp in the configuration used by that command.

7. Open an Interactive Shell

apptainer shell \
  --bind "$PWD:/work" \
  --bind "$BFF_TOOLS_DATA:/beacon2-cbi-tools-data" \
  --env BFF_TOOLS_DATA=/beacon2-cbi-tools-data \
  beacon2-cbi-tools.sif

Direct apptainer exec commands are preferred in scheduler scripts because they preserve the full invocation in the job record.

8. Slurm Example

#!/usr/bin/env bash
#SBATCH --cpus-per-task=8
#SBATCH --mem=32G
#SBATCH --time=24:00:00
#SBATCH --tmp=200G

set -euo pipefail
module load apptainer
export BFF_TOOLS_DATA=/shared/beacon2-cbi-tools-data

apptainer exec \
  --bind "$SLURM_SUBMIT_DIR:/work" \
  --bind "$BFF_TOOLS_DATA:/beacon2-cbi-tools-data" \
  --env BFF_TOOLS_DATA=/beacon2-cbi-tools-data \
  /shared/images/beacon2-cbi-tools.sif \
  bff-tools vcf -i /work/cohort.vcf.gz \
  --genome hg38 \
  --dataset-id cohort-1 \
  -t "$SLURM_CPUS_PER_TASK" \
  -o /work/cohort-bff

Adjust wall time, memory, and scratch space to the cohort. mem in config.yaml controls only the Java heap and must remain below the scheduler memory request.

Verification

apptainer exec beacon2-cbi-tools.sif bff-tools validate --help
apptainer exec beacon2-cbi-tools.sif bff-tools vcf --help

After binding the complete annotation bundle, process a small representative VCF with the production configuration before starting a cohort-scale run. Image and bundle maintainers can additionally run the packaged compact integration test.

Common HPC Problems

• Quota exceeded: move APPTAINER_CACHEDIR and APPTAINER_TMPDIR to project storage.
• Configured file not found: confirm the bind source exists and BFF_TOOLS_DATA names its destination inside the container.
• SnpEff database missing: verify $BFF_TOOLS_DATA/databases/snpeff/v5.0; the command supplies this directory directly and does not download databases.
• Permission denied: ensure output and scratch bind sources are writable by the submitting user.
• Killed by scheduler: keep the Java heap below the requested memory and account for bcftools, compression, and filesystem cache.
• Slow shared storage: use node-local scratch for intermediates when site policy permits, then copy final output and provenance back to project storage.

Keep the image tag or checksum, annotation-bundle version, configuration, and scheduler script together in run provenance. Do not run full annotation jobs on login nodes.

MongoDB

Apptainer provides no database service. Install MongoDB clients separately when needed and follow the MongoDB import guide.