Install FastaLake#
For a first run, use Docker: it bundles the tools and example inputs. A cluster that does not allow Docker can use the source installation.
Published image#
With Docker installed, download the bundled release:
The image includes Python, compiled Rust tools, Sage, directLFQ, AlphaPeptTools and example inputs. Continue with the quickstart. It targets Linux x86_64; Apple Silicon uses Docker's x86_64 emulation.
Choose an installation#
| Route | Use when |
|---|---|
| Published Docker image | You want a bundled release and a first result |
| Build Docker from source | You need changes on the current development branch |
| Source installation | You develop in Python or use a Linux cluster |
| Apptainer / Slurm | Your cluster runs containers through Apptainer |
| CI image artifact | You are testing a particular development commit |
The published image is v1.1.0rc2; newer changes on main enter the next
release. The container includes the official Sage v0.14.7 release binary
(which reports version 0.14.6), directLFQ 0.3.3 and AlphaPeptTools 0.4.0.
The Python runtime is hash-pinned in requirements/container.txt for Linux
x86_64 and Python 3.12.
Docker, built from the checkout#
From the repository root:
The first build downloads the base images and dependencies and compiles Rust. Allow several minutes and sufficient Docker memory for compilation. Builds default to two compiler jobs; use --build-arg CARGO_BUILD_JOBS=1 if memory is limited. Subsequent builds reuse Docker's cache. Python wheels are mounted temporarily during installation so the runtime image does not retain a second copy of the dependency archives (Docker build mounts).
The image targets Linux x86_64, matching the bundled Sage binary. On an Apple Silicon Mac, keep --platform linux/amd64 in both build and run commands; Docker Desktop must support x86_64 emulation. The earlier core-only image was built and its synthetic, CAMPI and HSTOOL acceptance tests passed on an Apple Silicon Mac with Docker Desktop 4.46.0 (Engine 28.4.0) on 12 September 2026. The tests used amd64 emulation, a non-root user, no network and a read-only root filesystem. The exported archive was reloaded and its CLI verified.
Download a tested image#
Open a successful run in Docker examples on GitHub
and download its fastalake-docker-linux-amd64 artifact. Choose the source commit
you want to use. GitHub keeps these artifacts for 14 days and applies repository
access rules. Unpack the download and open a terminal in that folder:
shasum -a 256 -c SHA256SUMS
docker load -i fastalake-docker-linux-amd64.tar.gz
bash test_container.sh ghcr.io/mannlabs/fasta-lake:local demo_run_01
On Linux, sha256sum --check SHA256SUMS is an alternative. The download includes
the matching demo script, README, image identity and source commit, so this route
needs Docker and Bash without a source checkout or compiler. Keep those files
with the demo results. The workflow tests the image before export, then reloads
the archive and checks that the image identity matches.
Versioned releases#
The release workflow publishes a successfully tested image to
ghcr.io/mannlabs/fasta-lake, tagged with the release version and full source SHA.
Use the version shown on the corresponding GitHub release:
# Set this to an existing published release tag.
FASTALAKE_RELEASE=YOUR_RELEASE_TAG
docker pull --platform linux/amd64 "ghcr.io/mannlabs/fasta-lake:$FASTALAKE_RELEASE"
docker tag "ghcr.io/mannlabs/fasta-lake:$FASTALAKE_RELEASE" ghcr.io/mannlabs/fasta-lake:local
Until a versioned release and its container job complete, use a tested-image
download above or build from the checkout. Repository and package access
rules still apply; private packages require an authorized GHCR login. Published
non-prerelease versions also update latest; use a version or digest for a
reproducible run.
Source installation#
From the repository root, the locked route is Python 3.12 on Linux x86_64: it installs
the same hash-pinned package set as the container and CI
(requirements/container.txt), so a native run and a container run see the
same Python dependencies. One pinned package (directLFQ) builds from source, so
a C compiler is needed. Add the pinned Rust toolchain and a separately
installed Sage v0.14.7. Use the official Linux x86_64 release asset
sage-v0.14.7-x86_64-unknown-linux-gnu.tar.gz
(archive SHA-256 e3dc6b41015cb167574f6c82525b75e946c094f30bd700271b05c051c30cbe8a);
the same archive is bundled at examples/campi/runtime/. Its executable reports
sage 0.14.6 because upstream did not change the version string for this tag, so
fasta-lake run identifies it by executable SHA-256
d3820543a31bfa2a556e04f91719204ce0ac6f34dcca6670314a13df87064625 and warns for any other
Sage binary (including the v0.14.6 release, a self-built or a macOS build), because
results may then differ from the validated configuration:
python -m venv .venv
source .venv/bin/activate
python -m pip install --require-hashes -r requirements/container.txt
python -m pip install --no-deps '.[analysis,directlfq]'
for crate in fasta_extractor_v2 parsimony_engine aggregation_engine; do
cargo build --release --locked --manifest-path "rust/$crate/Cargo.toml"
done
export PATH="$PWD/rust/fasta_extractor_v2/target/release:$PWD/rust/parsimony_engine/target/release:$PWD/rust/aggregation_engine/target/release:$PATH"
FastaLake needs Python 3.11 or newer; the tested and locked environment is 3.12.
Other Python versions and other platforms can install with
python -m pip install '.[analysis,directlfq]' instead of the two locked lines,
but then dependency versions float with PyPI and results are not the CI-tested
ones.
The Python wheel contains Python code; Rust executables are separate.
FASTALAKE_BIN_DIR can point to a directory containing those executables.
Run fasta-lake --help to list the commands and fasta-lake run --help for
the study runner. The function map explains the library underneath.
Verify the installation#
The complete check builds the image and runs every bundled example inside it, offline, with a 4 GiB memory limit and two CPU slots:
The command builds the combined Linux x86_64 image, then runs each test container with a 4 GiB memory limit and two CPU slots, without network access and with a read-only container filesystem. The build has separate resource requirements. Apple Silicon uses Docker's x86_64 emulation. You do not need host Python, Rust, Sage, directLFQ or AlphaPeptTools installations.
The first build downloads dependencies and compiles Rust. Tests cover the synthetic selection example, measured public CAMPI windows, exact molecular additions, real-data directLFQ/QC, and a separate synthetic PCA/missingness example. The two-acquisition CAMPI example correctly skips PCA; no extra acquisitions are invented for it.
Successful tests end with PASS. Keep the new docker_check_01/ directory and
logs for the integration review. Existing output directories are refused.
The check builds locally and does not publish an image.
For actual inputs and registry release instructions, see the Docker guide.
To verify an existing image, or carry it to a computer without internet:
bash tools/test_container.sh ghcr.io/mannlabs/fasta-lake:local docker_check
docker image inspect ghcr.io/mannlabs/fasta-lake:local --format '{{.Id}}'
docker save -o fastalake-docker-linux-amd64.tar ghcr.io/mannlabs/fasta-lake:local
gzip fastalake-docker-linux-amd64.tar
# On the receiving computer:
docker load -i fastalake-docker-linux-amd64.tar.gz
Run and verify the image before travel; then the example runs need no internet. GitHub Actions retains the tested image archive for 14 days on branch and pull-request runs. A published GitHub release additionally publishes that same tested image to GHCR. Record the source commit and image ID for reproducibility. Rust and all runtime Python dependencies are pinned. Base-image tags, OS packages and build tooling are not a fully immutable build lock. Record the image digest.
The container test runs all executable help checks, the synthetic examples, the public CAMPI real-data example, the additive metaG/metaT/metabolite workflow on real CAMPI spectra with synthetic molecular values, directLFQ and AlphaPeptTools QC on the CAMPI output, and PCA on a separately labelled three-acquisition synthetic fixture, with networking disabled and the container filesystem read-only. It also checks that Cargo and a C compiler are absent and that an existing output cannot be overwritten. Test results validate execution and expected outputs, not full-procedure FDR calibration.