Skip to content

Advanced installation details

Start with installation. This reference explains standalone builds, alternative backends, ownership checks and recovery behavior.

Install from GitHub

For development, install an editable checkout from the main branch:

git clone --branch main https://github.com/cfarkas/oncotracer.git oncotracer-src
python3 -m venv oncotracer-env
oncotracer-env/bin/python -m pip install -e ./oncotracer-src
source oncotracer-env/bin/activate

Keep both folders for this route. A normal pip install oncotracer includes the application and its resources without requiring a checkout.

The main branch includes the complete Illumina GLIMPSE2 workflow and resume/FFPE repairs. For Docker, use the current image documented below or build from source with both source provenance arguments.

OncoTracer v2 runs on Linux as one verified global executable. Python 3.10–3.13 is required by the portable zipapp. The selected backend supplies BWA, samtools, Picard, R, qDNAseq, HMMcopy, ichorCNA, the optional classifier, and GISTIC2.

Choose the installation route

Goal Use
First CNA analysis Standard installation, then the Conda section below.
CNA and small variants The pip application plus managed variant tools, or the current source Docker image.
HPC CNA analysis The Singularity/Apptainer section below.
Develop the launcher The Poetry section below.
Move a project to a remote server Headless setup and SSH.

Choose one backend per run. Conda and Poetry install both the core CNA tools and the shared Illumina variant tools. Caller-specific FFPE/ONT runtimes and models remain separate. Installing tools, downloading reference/model data, and starting an analysis are separate steps.

Requirements

Before installation, provide:

  • a Linux x86-64 host for the supplied scientific environments and container images;
  • Python 3.10–3.13;
  • enough storage for FASTQs, hg38, BAMs, environments, temporary files, and results;
  • sufficient available RAM, not just installed RAM; see the planning check below;
  • one backend: Conda, Docker, or Singularity/Apptainer.

For a first run, Conda is the recommended backend. Miniforge installation instructions cover installing Conda itself. oncotracer install --conda installs OncoTracer's analysis tools after Conda is available.

Use oncotracer system --path /path/to/project before installation, and oncotracer check --config /path/to/run.yml before analysis. They report CPU allowance, available RAM and free disk, including visible container limits.

For small LP-WGS jobs, 16 GiB available RAM for Illumina or 24 GiB for ONT is a conservative starting estimate with 2–4 threads, not a measured minimum or a guarantee. More threads, larger cohorts, finer bins and optional models need more. Native analysis uses BWA 0.7.19, not BWA-MEM2; a blanket 80-GiB indexing requirement does not describe this engine. The BWA manual describes its separate indexing algorithms. Prebuilt indexes avoid construction, but must still fit in memory during alignment. Swap is not a substitute for RAM.

Start with at least 60 GiB free for tools, reference assets and a small run; add space for your FASTQs, BAMs and temporary copies. Large runs need much more.

The first analysis can take substantially longer because the reference, indexes, packages, and container layers are prepared. If lpwgs_root/references/samurai_hg38 already exists, OncoTracer treats it as an external, read-only shared reference: every pinned file, index manifest, physical reader lock, and tool identity must validate, and OncoTracer will stop instead of repairing it in place. A plain existing FASTA/index directory is not auto-adopted. When that path is absent, FASTA/index, ichorCNA, and qDNAseq assets go to OncoTracer-owned, content-addressed caches below lpwgs_root/.oncotracer/reference-cache/. Later analyses reuse those validated assets even when they use a fresh result directory. Conda channel URLs are retained as informational provenance, but portability validity is based on stable package metadata and the exact indexing-executable SHA-256.

Standalone executable

The developer guide explains how to build a standalone command from an exact source commit.

The copied executable is a deterministic Python zipapp containing the versioned OncoTracer source payload. It does not require a Git clone after installation.

Normal commands that need bundled scripts verify and reuse a content-addressed cache at $XDG_CACHE_HOME/oncotracer/2.1.0/<executable-sha256>/payload (or $HOME/.cache when XDG_CACHE_HOME is unset). Each executable digest is isolated, and the exact payload inventory is checked before reuse. --dry-run instead uses an automatically removed temporary payload: it does not populate the persistent cache, save installation state, create results or environments, or pull an image/SIF.

Keep these release files together for audit:

oncotracer
SHA256SUMS
release-provenance.json
oncotracer-v2.1.0-parity-audit.tar.gz

release-provenance.json records the exact release commit, deterministic source archive SHA-256, executable SHA-256, stable container digest, and the successful QuickStart workflow and artifact identities. The values emitted by oncotracer provenance --json must agree with that record.

Command available from any directory

A successful oncotracer install creates an extra ~/.local/bin/oncotracer command when needed and preserves an existing pip-owned command. The extra launcher binds the Python interpreter and application location used to install it, so later terminals do not need environment activation. Keep the source and virtual environment for an editable installation, or the original archive for a standalone installation. It preserves the directory and arguments supplied by the caller.

If ~/.local/bin is absent from PATH, installation prints the export command needed for the current terminal. Add that directory to your shell's PATH for future sessions; the installer does not edit shell startup files. --no-launcher skips global command installation. Installation refuses an existing foreign or modified command rather than overwriting it. If you already placed the standalone archive itself at ~/.local/bin/oncotracer, use install --no-launcher to retain it there.

Normal uninstall also removes the global command when its recorded application and backend match the removal target. Use oncotracer uninstall --global-launcher --yes --purge to remove only an extra OncoTracer-owned command. Pip-owned commands are removed by pip instead. Remove any extra launcher before uninstalling the Python package.

A command or settings publication failure does not undo already prepared analysis tools. Retry using the original application and target. If an interrupted command transaction is reported, preserve its printed journal and recovery folder; those records identify the previous command files and paths needed for recovery.

Prepare exactly one backend

The installation choice is saved under the user's OncoTracer configuration directory. You may still override it per run with --backend.

Conda

Install Miniforge or a compatible Conda distribution, then run:

oncotracer install --conda
oncotracer doctor --backend conda

Six isolated, versioned scientific environments are created:

  • core alignment, Picard, refinement, CNA notation, and plotting tools;
  • qDNAseq with its pinned R 4.1 stack;
  • ichorCNA/HMMcopy with its pinned R 4.4 stack;
  • the optional CNA classifier/report stack;
  • GISTIC2 for the optional recurrence branch;
  • shared Illumina variant tools, including bcftools 1.23.1 linked to HTSlib 1.24, samtools, GATK, FreeBayes and Varlociraptor.

Separating the environments avoids incompatible R and compiled-library constraints. The default location is below the user's versioned OncoTracer data directory. Use an explicit shared location when required:

oncotracer install --conda \
  --prefix /srv/oncotracer/2.1.0/envs

oncotracer doctor --backend conda

For a scientific prefix root B, the mandatory variant environment lives at B-variants/variants. It is installed and checked by the same command. Its verified prefix is saved in the installation settings and selected by managed Illumina setup and runs, even if an older configuration names an unrelated Conda environment. The replacement is reported before analysis. The optional ffperase and strelka2 environments are created separately; see variant installation commands. Existing ANNOVAR software and databases are also separate. Setup resource autodetection inspects these installations without installing them. Approved public model/resource downloads occur only when Run starts.

Use --force only when deliberately rebuilding managed prefixes. Compatible, authenticated scientific environments are reused during application upgrades.

The prefix parent must be absent, empty, or already owned by this OncoTracer installer. OncoTracer never adopts a populated Conda directory or an unmarked fixed child (core, qdnaseq, ichorcna, classifier, gistic, or the optional Poetry runtime). Strict markers bind each managed path to an install ID, environment definition, exact file inventory, and OncoTracer source identity. Creation and updates run under an ownership-checked lock. For an owned replacement, OncoTracer journals the operation, moves only the verified old child to a same-filesystem backup, and creates the new Conda or Poetry environment directly at its final canonical prefix. Semantic probes and the exact inventory must pass there before commit; interruption restores the prior child. An unsealed tree left by SIGKILL is moved to a reported sibling oncotracer-preserved path rather than deleted. Shared runtime locks keep an installer from replacing a prefix while an analysis is consuming it. --force applies only to an intact owned installation and refuses prefixes used by active processes. Unrelated siblings under an owned prefix parent are preserved.

Docker

Install Docker Engine and ensure the current user can access the daemon:

docker info
oncotracer install --docker
oncotracer doctor --backend docker

The default installer pulls carlosfarkas/oncotracer:terminal-progress-20261022, validates its tools and saves the image reference. The older ghcr.io/cfarkas/oncotracer:2.1.0 remains available for earlier CNA workflows. It does not install Docker, alter daemon settings, or request administrator privileges silently.

Run an analysis with:

oncotracer run --backend docker \
  --config /absolute/path/project/config/illumina.auto.yml

All paths in the YAML should be absolute. OncoTracer derives the required project mounts from the configuration.

To build locally instead, use the current source image build, then install that local image with --no-pull.

Choose the current image explicitly when installing. Later doctor and run commands use the saved image selection:

oncotracer install --docker --image carlosfarkas/oncotracer:terminal-progress-20261022
oncotracer doctor --backend docker
oncotracer run --backend docker \
  --config /absolute/path/project/config/run.yml

Create that variant-enabled YAML with the browser or terminal variant guide. Installing an image alone does not enable variants. Automatic model preparation also requires the profile/license choices documented there.

Singularity or Apptainer

Install Apptainer or SingularityCE, then run:

oncotracer install --singularity
oncotracer doctor --backend singularity

Apptainer is preferred when both commands are present. The native v2 image is converted to a reusable SIF below the user's OncoTracer data directory.

Choose a shared SIF path when needed:

oncotracer install --singularity \
  --sif /srv/oncotracer/images/oncotracer-2.1.0.sif

oncotracer run --backend singularity \
  --config /absolute/path/project/config/illumina.auto.yml

The first installation requires an absent SIF destination. OncoTracer writes a strict .oncotracer.json sidecar that binds the canonical path, source image, SIF SHA-256, install ID, and OncoTracer source identity. Reuse rechecks the sidecar and bytes, then verifies the native doctor and container provenance inside the image. --force is accepted only for an owned pair: a new image is pulled to a same-directory transaction, verified before publication, and atomically swapped with rollback protection. Existing unowned files, symlinks, hard-linked files, malformed sidecars, and active images fail closed without being removed.

After any committed Conda, Poetry, or SIF transaction, OncoTracer retains the authenticated rollback tree and its journal instead of deleting either one. They are reported on standard error and stored beside the installation target:

.<target>.oncotracer-<kind>-txn-<transaction-id>.oncotracer-retained
.oncotracer-<kind>-retained-journal-<transaction-id>-<target-binding>.json

These transaction-ID-bound paths are ignored by later installs, so an interrupted journal-retention step can be resumed and a new install can proceed without overwriting earlier evidence. OncoTracer never automatically removes retained rollback or audit material. An administrator may archive or remove an exact reported path only after inspecting it and confirming that no OncoTracer install is running; never use a wildcard cleanup command.

Failed publications use the same rule: after restoring the prior target, OncoTracer writes a durable rolled_back journal, seals the exact rollback inventory, and retains both records. A later invocation can resume between any of those steps without overwriting earlier evidence.

Poetry

Poetry 2.0 or newer is required. Poetry is a source-development route, not the normal binary installation. Clone the repository only for development.

git clone https://github.com/cfarkas/oncotracer.git
cd oncotracer
./oncotracer install --poetry \
  --prefix /path/to/my/oncotracer-v2-dev-envs

/path/to/my/oncotracer-v2-dev-envs-poetry/poetry-runtime/bin/oncotracer --version
/path/to/my/oncotracer-v2-dev-envs-poetry/poetry-runtime/bin/oncotracer doctor \
  --backend poetry

./oncotracer install --poetry installs the locked Python launcher into the explicit, OncoTracer-owned poetry-runtime child and creates the same five core Conda environments plus the verified variant environment. It does not select or modify Poetry's global environment, another checkout's virtual environment, or an existing unowned prefix. OncoTracer first builds a wheel from an exact clean checkout in an isolated transaction tree, then invokes only the final virtual environment's Python and pip to install that wheel with dependencies and indexes disabled. Poetry's configuration, data, build environment, and caches remain inside the transaction; the checkout, ambient interpreter, global site-packages, and checkout-local .venv are unchanged. Poetry alone does not provide R, BWA, samtools, Picard, HMMcopy, ichorCNA, or GISTIC2.

Installer options are backend-specific. --prefix is accepted only for Conda and Poetry, while --image and --sif apply only to the relevant container backend. OncoTracer rejects irrelevant combinations instead of silently ignoring a path or force request.

Verify provenance and health

Run these checks after installation or an ownership-verified replacement. Managed Conda and Poetry prefixes are canonical-path-bound and must not be moved:

oncotracer --version
oncotracer provenance --json
oncotracer doctor --backend conda

For Docker or Singularity, substitute the selected backend. doctor performs semantic probes rather than checking only whether file names exist.

First analysis checklist

Before a large analysis:

  1. Run QuickStart 1 through the chosen backend.
  2. Confirm that the result summary reports engine=native and nextflow_used=false.
  3. Confirm that .oncotracer-native/trace.tsv is present.
  4. Place the project and reference cache on storage visible to the backend.
  5. Keep the installation and release provenance files with the study record.