Configuration

Almost everything an operator can change about a SeqDesk installation — the facility name, where sequencing data lives, whether pipelines run locally or on SLURM, which ENA account submissions use — is a setting. This section explains where settings live, which source wins when two of them disagree, and which settings a running application actually reads.

The mental model

There is one resolved configuration object. It is built by merging four sources, highest priority first:

Environment variables (SEQDESK_*) — process-level, set by the service unit or the shell that starts SeqDesk.
The config file (settings.json at the install root) — the reproducible, version-controllable description of the deployment.
The database (the SiteSettings singleton row) — everything a facility admin edits in the Admin UI.
Built-in defaults — compiled into the release.

The resolved object is cached in-process for 60 seconds, and every leaf value carries a source label (env, file, database, default) so you can always answer “why is this value what it is”. That answer is one API call away: GET /api/admin/config/status, which also backs the Configuration Sources panel on the Platform Info page (sidebar Settings → Info).

The part that surprises people

The resolved configuration is not what every feature reads. Only a handful of subsystems consult it — pipeline execution, the data base path, notifications, and telemetry. Most feature code reads the SiteSettings row directly.

That means a settings.json section such as ena or access is not a live control on a running server: it is an input that the installer, a hosted install profile, or Admin → Infrastructure → Import writes into the database, after which the database is what the feature reads. Editing that section on a running install and restarting will change what /api/admin/config/status reports and change nothing else.

Configuration Sources & Priority has the full table of which subsystems read which source. Read it before you conclude a setting is broken.

Where to start

Installing for the first time? The installer writes a working settings.json for you. Do not hand-write one first — see Installation and settings.json.
Changing something on a running install? Prefer the Admin UI. See Runtime Settings for what is editable there and what needs a restart.
Scripting a reproducible deployment? Put non-secrets in settings.json, secrets in environment variables, and apply both at install time with --config or --profile.
A value is not taking effect? Start at Configuration Sources & Priority, section When a setting appears to be ignored.

Configuration Sources & PriorityThe merge order, the source labels, which subsystem reads which source, and how to debug an ignored value.Environment VariablesEvery SEQDESK_ variable the code reads: config mappings, app-runtime switches, installer inputs, and compatibility-only names.Config File Referencesettings.json discovery, every section and key, defaults, and what is applied at install time versus read at runtime.Runtime Settings (Admin UI)Which admin screen owns which setting, where it is stored, and how quickly a change applies.

Neighbouring sections

Installation — how the first settings.json gets written, unattended installs, and hosted install profiles.
Administration — task-oriented guides for the admin screens named here: Data Storage, Pipeline Runtime, ENA Credentials, and Operational Telemetry.
Updates & Maintenance — settings.json lives at the install root and is symlinked into each release, so it survives updates and rollbacks unchanged.

SeqDesk and this documentation were developed with assistance from generative AI tools (Claude Code, Codex), and reviewed and tested by the maintainers. Generative AI disclosure