Docker

.dockerignore

@@ -0,0 +1,16 @@
+# Docker COPY does not honor .gitignore, so exclude host build artifacts and bulk here.
+# Keeping the context lean also avoids baking a stale local bin/ build into the image.
+.git
+bin/
+*.sif
+*.o
+temp_dac/
+testRun/
+.idea/
+cmake-build-debug/
+rufus_figure.pdf
+rufus_figure.png
+rufus_figure.py
+rufus_figure.pdf
+src/externals/jellyfish-2.2.5/
+src/externals/gkno_launcher/

.github/workflows/build-publish.yml

@@ -0,0 +1,121 @@
+name: build-publish
+
+# Tag mapping:
+#   push to docker / dev   -> stefinfection/rufus:dev      (development)
+#   push to main           -> stefinfection/rufus:stage    (staging)
+#   push git tag v*        -> stefinfection/rufus:<version> + :latest, then SIF -> Zenodo (prod)
+on:
+  push:
+    branches: [docker, dev, main]
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  IMAGE: stefinfection/rufus
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.meta.outputs.version }}
+      primary_tag: ${{ steps.meta.outputs.primary_tag }}
+    # Records a deployment to the matching GitHub Environment, giving a glanceable dev/stage/prod
+    # dashboard. The name is derived from the git ref (must be known at job start, so it uses the
+    # github context, not a step output). Arm the release gate by adding a required reviewer to the
+    # `production` environment in the repo settings — a v* tag build then waits for approval here.
+    environment:
+      name: ${{ startsWith(github.ref, 'refs/tags/v') && 'production' || github.ref == 'refs/heads/main' && 'staging' || 'development' }}
+      url: https://hub.docker.com/r/stefinfection/rufus/tags
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive   # src/modifiedJellyfish is a submodule the image build needs
+
+      - name: Resolve version and image tags
+        id: meta
+        run: |
+          # RUFUS_VERSION lives in resources/globals.txt as RUFUS_VERSION="vX.Y.Z"
+          VERSION=$(grep -E '^RUFUS_VERSION=' resources/globals.txt | cut -d'"' -f2)
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+          REF="${GITHUB_REF}"
+          if [[ "${REF}" == refs/tags/v* ]]; then
+            TAGNAME="${REF#refs/tags/}"
+            # Release guard: a prod tag must match RUFUS_VERSION in globals.txt, so the git tag,
+            # the image tag, the OCI version label, the runtime banner, and the Zenodo version
+            # can never disagree. Fail the release rather than publish an inconsistent one.
+            if [[ "${TAGNAME}" != "${VERSION}" ]]; then
+              echo "::error::Release tag '${TAGNAME}' does not match RUFUS_VERSION '${VERSION}' in resources/globals.txt. Bump globals.txt (and commit) before tagging, or retag to match." >&2
+              exit 1
+            fi
+            echo "tags=${IMAGE}:${TAGNAME},${IMAGE}:latest" >> "$GITHUB_OUTPUT"
+            echo "primary_tag=${TAGNAME}" >> "$GITHUB_OUTPUT"
+            echo "is_release=true" >> "$GITHUB_OUTPUT"
+          elif [[ "${REF}" == refs/heads/main ]]; then
+            echo "tags=${IMAGE}:stage" >> "$GITHUB_OUTPUT"
+            echo "primary_tag=stage" >> "$GITHUB_OUTPUT"
+            echo "is_release=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "tags=${IMAGE}:dev" >> "$GITHUB_OUTPUT"
+            echo "primary_tag=dev" >> "$GITHUB_OUTPUT"
+            echo "is_release=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Runs on every build, not just releases, so drift is caught on a dev push to
+      # `docker` rather than at the moment of tagging. Fix with: --write
+      - name: Check doc version strings match globals.txt
+        run: bash scripts/ci/check_doc_versions.sh
+
+      - uses: docker/setup-buildx-action@v4
+
+      # Build locally first (load into the runner's docker) so the smoke test can gate the push.
+      - name: Build image
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          load: true
+          tags: ${{ env.IMAGE }}:ci-${{ github.sha }}
+          build-args: |
+            RUFUS_VERSION=${{ steps.meta.outputs.version }}
+
+      - name: Smoke test
+        run: docker run --rm ${{ env.IMAGE }}:ci-${{ github.sha }} bash /opt/RUFUS/tests/smoke_test.sh
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Re-tag the validated image and push. (The smoke test already ran on this exact build.)
+      - name: Tag and push
+        run: |
+          IFS=',' read -ra TAGS <<< "${{ steps.meta.outputs.tags }}"
+          for t in "${TAGS[@]}"; do
+            docker tag "${IMAGE}:ci-${{ github.sha }}" "$t"
+            docker push "$t"
+          done
+
+  release:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install apptainer
+        uses: eWaterCycle/setup-apptainer@v2
+
+      - name: Build SIF from the published image
+        run: |
+          apptainer build "rufus_${{ needs.build.outputs.primary_tag }}.sif" \
+            "docker://${IMAGE}:${{ needs.build.outputs.primary_tag }}"
+
+      - name: Upload new version to Zenodo
+        env:
+          ZENODO_TOKEN: ${{ secrets.ZENODO_TOKEN }}
+          ZENODO_CONCEPT_RECORD_ID: ${{ secrets.ZENODO_CONCEPT_RECORD_ID }}
+        run: |
+          bash scripts/ci/zenodo_upload.sh \
+            "rufus_${{ needs.build.outputs.primary_tag }}.sif" \
+            "${{ needs.build.outputs.primary_tag }}"

.gitignore

@@ -4,6 +4,20 @@ src/externals/jellyfish-2.2.5/
 src/externals/gkno_launcher/
 cloud/1000G.RUFUSreference.sorted.min45.tab
 *.o
-*test*
-idea/
-idea/*
+# Note: a blanket `*test*` rule used to live here. It silently dropped tracked files whose
+# path contained "test" (our tests/ suite, and modified-jellyfish's tests/ dir), so it was
+# removed. Add narrow, specific ignores here if test scratch output needs excluding.
+# SLURM writes job logs beside the case scripts when you sbatch from tests/functional/cases/.
+# Deliberately path-scoped and extension-scoped -- do NOT broaden these to `*test*` or `*.out`.
+tests/functional/cases/*.out
+tests/functional/cases/*.err
+.idea/
+.idea/*
+cmake-build-debug/*
+cmake-build-debug/
+singularity/rufus_v1.0.0-epsilon.sif
+temp_dac/
+cleanup.sh
+rufus_figure.pdf
+rufus_figure.py
+rufus_figure.png

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "src/modifiedJellyfish"]
+	path = src/modifiedJellyfish
+	url = https://github.com/stefinfection/modified-jellyfish.git

Dockerfile

@@ -0,0 +1,102 @@
+# RUFUS — canonical container definition (single source of truth).
+# SIFs are built from this image via `apptainer pull/build docker://...`; there is no separate .def file.
+FROM ubuntu:22.04
+
+# Build-time version, passed by CI from resources/globals.txt (defaults to "dev" for local builds).
+ARG RUFUS_VERSION=dev
+
+LABEL author="Stephanie Georges"
+LABEL org.opencontainers.image.title="RUFUS"
+LABEL org.opencontainers.image.version="${RUFUS_VERSION}"
+LABEL org.opencontainers.image.source="https://github.com/stefinfection/RUFUS"
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Pinned external tool versions (last reviewed Jan 2025).
+ARG HTSLIB_VERSION="1.21"
+ARG BAMTOOLS_VERSION="v2.5.2"
+ARG BEDTOOLS_VERSION="2.31.1"
+
+# System + build dependencies. Most of these (parallel, gawk, vt, bc, libgsl, the lib*-dev
+# packages) are required at RUNTIME by runRufus.sh and the samtools/bcftools stack, so this
+# stays a single stage rather than a slimmed multi-stage build.
+# Note: the historical Dockerfiles added ppa:ubuntu-toolchain-r/test but never installed a
+# newer g++ from it -- the default ubuntu 22.04 g++ 11 builds RUFUS. The PPA was vestigial and
+# (under --no-install-recommends) broke the build on a missing gnupg, so it is dropped.
+RUN apt-get update && \
+    apt-get install -y \
+      git cmake wget g++ build-essential zlib1g-dev libbz2-dev bc \
+      libgsl0-dev libncurses5-dev autoconf automake make liblzma-dev \
+      libcurl4-gnutls-dev libssl-dev vt parallel gawk libjsoncpp-dev \
+      libjsoncpp25 curl unzip ca-certificates file && \
+    rm -rf /var/lib/apt/lists/*
+
+# AWS CLI — required at runtime: resource_helpers/download_hash.sh fetches region-specific
+# 1000G/control exclusion hashes from S3 via `aws s3 ... --no-sign-request`.
+RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && \
+    unzip -q awscliv2.zip && \
+    ./aws/install && \
+    rm -rf awscliv2.zip aws
+
+# htslib (provides bgzip/tabix + the libhts that samtools/bcftools link against) -> /usr/local.
+# Keep the /opt/htslib source tree so samtools/bcftools can build against it via --with-htslib;
+# run ldconfig so the runtime linker picks up the freshly installed /usr/local/lib/libhts.
+RUN cd /opt && \
+    git clone --recurse-submodules https://github.com/samtools/htslib.git --depth 1 --branch "${HTSLIB_VERSION}" && \
+    cd htslib && autoreconf -i && ./configure && make && make install && ldconfig
+
+# samtools -> /usr/local (linked against the /opt/htslib source above)
+RUN cd /opt && \
+    git clone https://github.com/samtools/samtools.git --depth 1 --branch "${HTSLIB_VERSION}" && \
+    cd samtools && autoheader && autoconf -Wno-syntax && \
+    ./configure --with-htslib=/opt/htslib && make && make install && \
+    cd /opt && rm -rf samtools
+
+# bcftools -> /usr/local (last htslib consumer; drop the htslib source tree afterward)
+RUN cd /opt && \
+    git clone https://github.com/samtools/bcftools.git --depth 1 --branch "${HTSLIB_VERSION}" && \
+    cd bcftools && autoheader && autoconf && \
+    ./configure --with-htslib=/opt/htslib --enable-libgsl && make && make install && \
+    cd /opt && rm -rf bcftools htslib
+
+# bamtools -> /usr/local
+RUN cd /opt && \
+    git clone https://github.com/pezmaster31/bamtools.git --depth 1 --branch "${BAMTOOLS_VERSION}" && \
+    cd bamtools && mkdir build && cd build && \
+    cmake -DCMAKE_INSTALL_PREFIX=/usr/local .. && make && make install && \
+    cd /opt && rm -rf bamtools
+
+# bedtools -> /usr/local/bin
+RUN cd /opt && \
+    wget -q "https://github.com/arq5x/bedtools2/releases/download/v${BEDTOOLS_VERSION}/bedtools-${BEDTOOLS_VERSION}.tar.gz" && \
+    tar -zxf "bedtools-${BEDTOOLS_VERSION}.tar.gz" && \
+    cd bedtools2 && make && cp bin/* /usr/local/bin/ && \
+    cd /opt && rm -rf bedtools2 "bedtools-${BEDTOOLS_VERSION}.tar.gz"
+
+# RUFUS — built from the checked-out source tree (not a pinned git clone), so each branch/tag
+# builds its own code. CMake fetches and builds the bundled externals (modified jellyfish, etc.).
+COPY . /opt/RUFUS
+RUN cd /opt/RUFUS && mkdir -p bin && cd bin && cmake ../ && make
+
+# Drop the largest build-only packages; keep the rest since runtime depends on them.
+RUN apt-get purge -y --auto-remove git wget && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+ENV DEBIAN_FRONTEND=
+ENV PATH=/opt/RUFUS/bin:${PATH}
+ENV RUFUS_ROOT=/opt/RUFUS
+# Pin bcftools to the plugins we built above. Without this the HOST's BCFTOOLS_PLUGINS is
+# inherited into the container (near-universal on HPC, where a bcftools module is usually
+# loaded), and our bcftools dlopens the host's mismatched plugin:
+#   fill-from-fasta.so: undefined symbol: bcf_format_gt_v2
+# which kills the VCF post-processing stage. Setting it here makes the image immune to host env.
+ENV BCFTOOLS_PLUGINS=/usr/local/libexec/bcftools
+ENV LC_CTYPE=en_US.UTF-8
+ENV LANG=en_US.UTF-8
+ENV LANGUAGE=en_US.UTF-8
+
+# Smoke test — fails the build if any expected binary or env var is missing.
+RUN bash /opt/RUFUS/tests/smoke_test.sh
+
+WORKDIR /data
+CMD ["/bin/bash"]