Environment Variables

Environment variables come in three quite different families, and confusing them is the most common source of “I set the variable and nothing happened”:

1. Configuration mappings — recognised by the configuration loader and merged into the resolved configuration at the highest priority. Whether that changes behaviour depends on whether the feature reads the resolved configuration; see Configuration Sources & Priority.
2. Application runtime switches — read directly by feature code with process.env. These always take effect, and none of them appear in /api/admin/config/status.
3. Installer inputs — consumed by install-dist.sh and the seqdesk launcher before the app starts. They have no effect on a running app.

Value parsing (family 1 only)

Variables in the configuration-mapping family are parsed by target type:

• Booleans — the literal strings "true" / "false", case-insensitive. Any other value is kept verbatim as a string, so write SEQDESK_SLURM_ENABLED=true, never SEQDESK_SLURM_ENABLED=1.
• Numbers — parsed as integers for paths containing slurm.cores, slurm.timeLimit, scanDepth, sessionTimeout, or intervalHours.
• Arrays — comma-separated and trimmed, e.g. ".fastq.gz,.fq.gz,.fastq,.fq". This applies to extensions and ignorePatterns.
• Strings — everything else.

1. Configuration mappings

Site

Pipelines

Pipeline execution reads the resolved configuration and lets env/file values override the admin-saved settings, so the execution variables are live.

Conda

Pipeline execution is Conda-only. SeqDesk always sets its pipeline runtime mode to Conda and adds the conda Nextflow profile when needed.

SLURM

MAG pipeline

Install-time inputs. On a running install these live in the PipelineConfig row for mag and are edited under Settings → Pipelines or per run.

Telemetry

Notifications

Email notifications additionally require the Email Notifications module to be enabled under Settings → Modules. Set the relay token through this variable — it is masked in /api/admin/config/status, and the Admin UI deliberately refuses to write it to the database.

Mapped, but the feature reads the database

These variables are recognised by the configuration loader and will show up in /api/admin/config/status with source env — but the corresponding feature reads the SiteSettings row, so setting them on a running server does not change behaviour. They are useful as install-time inputs (the installer and hosted profiles write them into the database) and as a way to see what a config file would produce.

To change any of these on a running install, use the Admin UI — see ENA Credentials, Data Storage, and Runtime Settings.

Accepted compatibility variables (unsupported)

The configuration loader still recognises these names so older configuration files and deployment manifests continue to parse. They are not functional controls:

There is currently no supported switch to disable Conda execution, reject all single-end reads, or set the authentication session lifetime. Do not use these variables to express an operational requirement.

2. Application runtime variables

These are read directly by feature code. They are not part of the configuration merge and do not appear in /api/admin/config/status.

Process environment

Each of these can also be supplied from the runtime section of settings.json. Those values are applied to process.env at startup only if the variable is not already set, so the environment always wins, and any change needs a restart.

Secrets at rest

Values are stored as enc:v1:<base64> with AES-256-GCM and an HKDF-derived key. Anything without that prefix is treated as legacy plaintext and re-encrypted the next time it is saved. Set SEQDESK_ENCRYPTION_KEY explicitly if you ever expect to rotate NEXTAUTH_SECRET: rotating the auth secret without a dedicated encryption key makes previously encrypted values undecryptable.

Updates

See Automatic Updates.

Pipelines and execution

Registries and integrations

Surface and development

3. Installer variables

These are consumed by install-dist.sh and the seqdesk launcher before the app starts. They have no effect on a running app — they configure the install flow itself. This is a practical subset, not an exhaustive list; see the unattended installation guide and seqdesk --help for the supported CLI surface.

Target and mode

Download integrity and network

Added so a slow or hostile network fails loudly instead of hanging, and so a regulated site can refuse an unverified package.

A checksum mismatch is always fatal and is never overridable. The Miniconda installer is fetched with no time ceiling, because it is large and often slow from institutional networks.

Miniconda source

The default is the rolling -latest- build, so two installs a month apart can get different Conda versions. Pin both variables when you need a reproducible environment for a methods section or a validated deployment.

Configuration source

Infrastructure overrides

Secrets

Pipeline toggles

Pipeline-execution overrides

These set runtime pipeline-execution settings at install time without editing a config file. They are written into SiteSettings.extraSettings.pipelineExecution during install, which is the same place Settings → Infrastructure → Pipeline Runtime writes.

When SEQDESK_EXEC_CONDA_PATH is set, it takes precedence over PATH and standard user-prefix discovery. A working existing base is reused. A path that does not exist may be created by the Miniconda installer. An existing path that does not contain a working Conda executable stops the install with recovery instructions; the installer does not delete it or silently select another location.

Private pipeline package (MetaXpath)

SEQDESK_METAXPATH_PACKAGE_URL and SEQDESK_METAXPATH_SHA256 are normally left unset: when only a MetaXpath token is provided, the release asset URL and SHA-256 digest are resolved automatically.

Form presets

These are installer inputs only. Settings → Infrastructure → Import settings.json deliberately ignores them and points you at the form import screens instead.

SeqDesk.com admin variables

These are used by the hosted SeqDesk.com admin service, not by an installed SeqDesk runtime. Configure them on the SeqDesk.com deployment when using install-profile administration features.

Examples

A SLURM facility, secrets in the unit file

# Site
export SEQDESK_SITE_NAME="My Sequencing Facility"
export SEQDESK_DATA_PATH="/mnt/sequencing/data"
 
# Pipeline execution on SLURM (enable the pipelines themselves under
# Settings -> Pipelines; this only pins where they run)
export SEQDESK_PIPELINE_MODE="slurm"
export SEQDESK_SLURM_ENABLED="true"
export SEQDESK_SLURM_QUEUE="bioinformatics"
export SEQDESK_SLURM_CORES="16"
export SEQDESK_SLURM_MEMORY="64GB"
export SEQDESK_SLURM_TIME="24"          # hours
 
# Shared conda cache so isolated compute nodes never fetch packages
export SEQDESK_CONDA_PATH="/net/software/conda"
export SEQDESK_CONDA_CACHE_DIR="/net/software/conda-cache"
 
# Secrets
export DATABASE_URL="postgresql://seqdesk:...@db.internal:5432/seqdesk?schema=public"
export NEXTAUTH_SECRET="$(openssl rand -base64 32)"
export SEQDESK_ENCRYPTION_KEY="$(openssl rand -base64 32)"

A reproducible, offline-friendly install

SEQDESK_REQUIRE_CHECKSUM=1 \
SEQDESK_MINICONDA_BASE_URL="https://mirror.internal/miniconda" \
SEQDESK_MINICONDA_INSTALLER="Miniconda3-py312_24.9.2-0-Linux-x86_64.sh" \
SEQDESK_CURL_DOWNLOAD_MAX_TIME=3600 \
SEQDESK_LOG=/var/log/seqdesk-install.log \
npx -y seqdesk@latest -y --with-pipelines --dir /opt/seqdesk

Related

• Configuration Sources & Priority — why an env variable may still not change behaviour
• Config File Reference — the settings.json equivalents
• Unattended installation — the full installer flag reference