build(docker): add container image for the toolkit CLI

Packages FinaleToolkit with a pinned Python and its compiled dependencies
(pysam, numba, pyBigWig, py2bit) so it runs identically on a laptop, in CI,
and on a cloud instance without reproducing the environment by hand.

Two-stage build: a builder stage produces a wheel, and a clean runtime stage
installs it, keeping compilers and build tooling out of the final image. A
third `test` stage adds pytest as a strict superset of the runtime image; the
~91MB of fixtures under tests/ are mounted at run time rather than baked in.

.git is excluded from the build context (~200MB), so setuptools-scm cannot
derive the version inside the container. docker/build.sh resolves it on the
host and passes it as SETUPTOOLS_SCM_PRETEND_VERSION, preferring setuptools-scm
and falling back to a git-describe implementation of guess-next-dev. The build
fails rather than shipping an image that reports itself as 0.0.0.dev0+unknown.

docker/verify.py runs as a build step and guards three failure modes that
would otherwise ship silently: the fallback version, missing package data
under frag/data and genome/data, and compiled wheels that do not load.

Targets linux/amd64 by default, since py2bit and pyBigWig do not reliably
publish prebuilt ARM Linux wheels.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jamesli124

.dockerignore

@@ -0,0 +1,39 @@
+# Paths excluded from the Docker build context -- the daemon never receives
+# them. The Dockerfile only COPYs pyproject.toml, MANIFEST.in, README.md,
+# LICENSE and src/, so this is about keeping builds fast, not correctness.
+
+# ~200MB of history. setuptools-scm would normally read the version from it;
+# docker/build.sh passes the version in as a build arg instead.
+.git
+.gitignore
+.github
+
+# ~91MB of BAM/CRAM/2bit fixtures. Mounted at run time by the "test" stage
+# rather than baked into the image.
+tests
+
+# Not needed to build or run the package.
+docs
+scripts
+.readthedocs.yaml
+CHANGELOG.md
+RELEASING.md
+
+# Build and test artifacts.
+build
+dist
+*.egg-info
+**/__pycache__
+**/*.pyc
+.pytest_cache
+.ruff_cache
+.coverage*
+
+# Local editor / OS cruft.
+.vscode
+.claude
+**/.DS_Store
+
+# Written by setuptools-scm during the build. A stale copy from a local
+# editable install would otherwise be copied in and shadow the real version.
+src/finaletoolkit/_version.py

Dockerfile

@@ -0,0 +1,124 @@
+# syntax=docker/dockerfile:1
+
+# Two-stage build. The first stage has the tooling needed to produce a wheel;
+# the second installs that wheel into a clean image, so the compilers and
+# build-time packages never ship in the final artifact.
+#
+# Build with docker/build.sh, which derives the version from git tags and
+# passes it in. See docker/README.md.
+
+ARG PYTHON_VERSION=3.12
+
+
+# --- Stage 1: build the wheel ------------------------------------------------
+FROM python:${PYTHON_VERSION}-slim AS builder
+
+# setuptools-scm normally derives the version from git history, but .git is
+# excluded from the build context (it is ~200MB, and shipping it to the daemon
+# on every build is slow). The version is passed in instead. Without this,
+# setuptools-scm silently falls back to "0.0.0.dev0+unknown" -- the runtime
+# stage asserts against exactly that.
+ARG SETUPTOOLS_SCM_PRETEND_VERSION
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=${SETUPTOOLS_SCM_PRETEND_VERSION}
+
+WORKDIR /src
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install build
+
+# MANIFEST.in and README.md are referenced by the build (readme is declared in
+# pyproject.toml), so the build fails without them even though only src/ ends
+# up in the wheel.
+COPY pyproject.toml MANIFEST.in README.md LICENSE ./
+COPY src/ ./src/
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    python -m build --wheel --outdir /dist
+
+
+# --- Stage 2: runtime --------------------------------------------------------
+FROM python:${PYTHON_VERSION}-slim AS runtime
+
+LABEL org.opencontainers.image.title="FinaleToolkit" \
+      org.opencontainers.image.description="Extract fragmentation features of cell-free DNA from paired-end sequencing data." \
+      org.opencontainers.image.source="https://github.com/epifluidlab/FinaleToolkit" \
+      org.opencontainers.image.documentation="https://epifluidlab.github.io/FinaleToolkit/" \
+      org.opencontainers.image.licenses="MIT"
+
+# numba and matplotlib both want a writable cache/config directory and fall
+# back to $HOME, which the non-root user below cannot always write to
+# (e.g. when the image is run with an arbitrary --user). Point them at /tmp,
+# which is writable regardless.
+#
+# PYTHONDONTWRITEBYTECODE is deliberately *not* set: pip precompiles .pyc
+# files at install time, and keeping them means the CLI does not re-parse
+# scipy/numba/matplotlib source on every invocation. This is a short-lived
+# process started many times, so startup cost matters more than image size.
+ENV NUMBA_CACHE_DIR=/tmp/numba-cache \
+    MPLCONFIGDIR=/tmp/matplotlib \
+    PYTHONUNBUFFERED=1
+
+# Bind-mounting the wheel rather than COPYing it keeps it out of the image's
+# layers -- the installed package is all we need.
+RUN --mount=type=bind,from=builder,source=/dist,target=/dist \
+    --mount=type=cache,target=/root/.cache/pip \
+    pip install /dist/*.whl
+
+# Two smoke checks that catch the failure modes that would otherwise ship
+# silently:
+#
+#  1. Version. Without SETUPTOOLS_SCM_PRETEND_VERSION the package falls back to
+#     "0.0.0.dev0+unknown" and the image is untraceable.
+#  2. Package data. The .tsv/.gz files under frag/data and genome/data are
+#     pulled in by [tool.setuptools.package-data]; if that ever stops working,
+#     the CLI installs cleanly and then fails at run time on the subcommands
+#     that need them.
+#  3. Imports. Loading the CLI module confirms the compiled wheels (pysam,
+#     numba, pyBigWig, py2bit) actually load on this base image.
+#
+# Bind-mounted rather than COPYed so the script leaves no layer behind.
+RUN --mount=type=bind,source=docker/verify.py,target=/tmp/verify.py \
+    python /tmp/verify.py
+
+RUN useradd --create-home --uid 1000 finaletoolkit \
+    && mkdir -p /data \
+    && chown finaletoolkit:finaletoolkit /data
+
+USER finaletoolkit
+
+# Conventional mount point for input BAM/CRAM files and outputs:
+#   docker run -v /host/path:/data <image> <subcommand> /data/sample.bam ...
+WORKDIR /data
+
+# ENTRYPOINT makes the image behave as the CLI itself, so `docker run <image>
+# frag-length-bins ...` works the same way the installed command does.
+ENTRYPOINT ["finaletoolkit"]
+CMD ["--help"]
+
+
+# --- Stage 3: test -----------------------------------------------------------
+# A strict superset of the runtime image: same environment, plus pytest. The
+# 91MB of fixtures under tests/ are mounted at run time rather than baked in.
+#
+#   docker build --target test -t finaletoolkit:test .
+#   docker run --rm -v "$PWD/tests:/app/tests:ro" --entrypoint pytest \
+#       finaletoolkit:test
+#
+# The ENTRYPOINT is deliberately left as-is so this image still works as a
+# plain CLI if it is built by accident (it is the last stage, so a bare
+# `docker build .` lands here).
+FROM runtime AS test
+
+USER root
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install pytest pytest-cov
+
+# pytest reads [tool.pytest.ini_options] from pyproject.toml, which sets
+# testpaths = ["tests"]; this also makes /app the rootdir. It has to be
+# writable by the non-root user, since pytest writes .pytest_cache there and
+# --cov writes .coverage.
+RUN mkdir -p /app && chown finaletoolkit:finaletoolkit /app
+WORKDIR /app
+COPY --chown=finaletoolkit:finaletoolkit pyproject.toml ./
+
+USER finaletoolkit

docker/README.md

@@ -0,0 +1,97 @@
+# Container image
+
+A container image bundles FinaleToolkit with a pinned Python and all of its
+compiled dependencies (numpy, pysam, numba, pyBigWig, py2bit), so it runs
+identically on a laptop, in CI, and on a cloud instance without anyone having
+to reproduce the environment by hand.
+
+## Build
+
+```sh
+docker/build.sh
+```
+
+This tags `finaletoolkit:<version>` and `finaletoolkit:latest`, where
+`<version>` comes from git tags via setuptools-scm — the same version the wheel
+would get.
+
+Why a script rather than a bare `docker build`: `.git` is excluded from the
+build context (it is ~200MB), so setuptools-scm cannot derive the version
+inside the container. The script resolves it and passes it in as a build arg.
+Building by hand works too, as long as you supply it:
+
+```sh
+docker build --build-arg SETUPTOOLS_SCM_PRETEND_VERSION=1.1.0 \
+    --target runtime -t finaletoolkit:1.1.0 .
+```
+
+The build fails rather than producing an image that reports itself as
+`0.0.0.dev0+unknown`.
+
+Overrides, all optional:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `FTK_VERSION` | derived from git | Set the version explicitly |
+| `FTK_IMAGE` | `finaletoolkit` | Image name |
+| `FTK_PLATFORM` | `linux/amd64` | Target architecture |
+
+`linux/amd64` is the default because py2bit and pyBigWig do not reliably
+publish prebuilt ARM Linux wheels; on ARM they may have to compile from source.
+On Apple Silicon the resulting image runs under emulation — correct, but slow.
+
+## Run
+
+The image behaves as the `finaletoolkit` command itself:
+
+```sh
+docker run --rm finaletoolkit:latest --help
+docker run --rm finaletoolkit:latest --version
+```
+
+A container has its own filesystem that is discarded on exit, so input and
+output have to be bind-mounted from the host. `/data` is the conventional
+mount point and the image's working directory:
+
+```sh
+docker run --rm -v "/path/to/data:/data" finaletoolkit:latest \
+    frag-length-bins /data/sample.bam -o /data/output.tsv
+```
+
+Paths in the command are container paths, not host paths — `/data/sample.bam`
+refers to `/path/to/data/sample.bam` on the host.
+
+The container runs as a non-root user (uid 1000). On Linux, output files land
+on the host owned by that uid; add `--user "$(id -u):$(id -g)"` if you need
+them owned by you. Docker Desktop on macOS handles this mapping already.
+
+## Test
+
+The `test` stage is the runtime image plus pytest. The ~91MB of fixtures under
+`tests/` are mounted at run time rather than baked into the image:
+
+```sh
+docker/build.sh --target test
+docker run --rm -v "$PWD/tests:/app/tests:ro" \
+    --entrypoint pytest finaletoolkit:test
+```
+
+Tests write through pytest's `tmp_path` fixture, so the mount can stay
+read-only.
+
+Passing tests here is a stronger signal than passing on the host: it confirms
+the packaged environment is correct, not just that the code imports.
+
+## What is in the image
+
+Two stages. The first installs the build tooling and produces a wheel; the
+second installs that wheel into a clean `python:3.12-slim` base, so compilers
+and build-time packages never ship in the final artifact.
+
+The Python version is pinned to one version (3.12), unlike CI, which tests a
+3.10–3.13 matrix. That is intentional: the matrix proves the library is
+portable, while the image is a single reproducible deployment target.
+
+`NUMBA_CACHE_DIR` and `MPLCONFIGDIR` are pointed at `/tmp` because numba and
+matplotlib both want a writable cache directory and default to `$HOME`, which
+is not writable under an arbitrary `--user`.

docker/build.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# Build the FinaleToolkit container image.
+#
+# .git is excluded from the build context, so setuptools-scm cannot derive the
+# version inside the container. This script resolves it here and passes it in.
+#
+# Usage:
+#   docker/build.sh                  # build the runtime image
+#   docker/build.sh --target test    # build the test image instead
+#   FTK_VERSION=1.1.0 docker/build.sh
+#
+# Any extra arguments are forwarded to `docker build`.
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+
+image="${FTK_IMAGE:-finaletoolkit}"
+platform="${FTK_PLATFORM:-linux/amd64}"
+
+# Mirrors setuptools-scm's default version_scheme ("guess-next-dev") combined
+# with the local_scheme = "no-local-version" set in pyproject.toml:
+#
+#   exactly on tag v1.1.0, clean   -> 1.1.0
+#   4 commits past v1.1.0          -> 1.1.1.dev4
+#
+# Only used when setuptools-scm is not importable. If the version_scheme in
+# pyproject.toml ever changes, this needs to change with it.
+derive_version_from_git() {
+    local describe tag distance dirty base
+    describe="$(git describe --tags --long --dirty 2>/dev/null)" || return 1
+
+    dirty=""
+    if [[ "$describe" == *-dirty ]]; then
+        dirty="yes"
+        describe="${describe%-dirty}"
+    fi
+
+    # v1.1.0-4-g3ca99fd -> tag=v1.1.0, distance=4
+    tag="${describe%-*-g*}"
+    distance="${describe%-g*}"
+    distance="${distance##*-}"
+
+    base="${tag#v}"
+
+    if [[ "$distance" == "0" && -z "$dirty" ]]; then
+        printf '%s\n' "$base"
+        return 0
+    fi
+
+    # Bump the last numeric component: 1.1.0 -> 1.1.1
+    local prefix last
+    last="${base##*.}"
+    prefix="${base%.*}"
+    if [[ "$last" =~ ^[0-9]+$ ]]; then
+        printf '%s.%s.dev%s\n' "$prefix" "$((last + 1))" "$distance"
+    else
+        return 1
+    fi
+}
+
+# setuptools-scm is authoritative when available; the git fallback keeps this
+# script usable in an environment that only has the runtime dependencies.
+version="${FTK_VERSION:-}"
+if [[ -z "$version" ]]; then
+    version="$(python -m setuptools_scm 2>/dev/null || true)"
+fi
+if [[ -z "$version" ]]; then
+    version="$(derive_version_from_git || true)"
+    [[ -n "$version" ]] && echo "note: setuptools-scm unavailable; derived ${version} from git" >&2
+fi
+if [[ -z "$version" ]]; then
+    cat >&2 <<'EOF'
+error: could not determine the package version.
+
+setuptools-scm is not importable and the version could not be derived from git
+(no tags reachable, or not a git checkout). Either:
+
+    pip install setuptools-scm
+
+or set it explicitly:
+
+    FTK_VERSION=1.1.0 docker/build.sh
+EOF
+    exit 1
+fi
+
+# Default to the runtime stage. Without this a bare `docker build` would build
+# the last stage in the Dockerfile, which is the larger test image.
+target="runtime"
+args=()
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --target)
+            target="$2"
+            shift 2
+            ;;
+        --target=*)
+            target="${1#*=}"
+            shift
+            ;;
+        *)
+            args+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Non-runtime stages get a suffixed tag so that building the test image does
+# not overwrite the runtime image's tags.
+tags=()
+if [[ "$target" == "runtime" ]]; then
+    tags+=(--tag "${image}:${version}" --tag "${image}:latest")
+else
+    tags+=(--tag "${image}:${version}-${target}" --tag "${image}:${target}")
+fi
+
+echo "Building ${image} ${version} (target=${target}, platform=${platform})"
+
+set -x
+docker build \
+    --platform "$platform" \
+    --target "$target" \
+    --build-arg "SETUPTOOLS_SCM_PRETEND_VERSION=${version}" \
+    "${tags[@]}" \
+    "${args[@]+"${args[@]}"}" \
+    .