Configuration Sources & Priority

SeqDesk uses a multi-source configuration system. When the same setting exists in multiple sources, a clear priority order determines which value wins.

Priority Order

From highest to lowest priority:

How Resolution Works

When SeqDesk starts, it builds the final configuration by merging all sources using a deep merge strategy:

defaults ← config file ← environment variables

Database settings are merged separately and have the lowest priority — they only apply when no env var or config file value exists for that setting.

The resolved configuration is cached for 60 seconds for performance. Source tracking records where each value came from.

When to Use Each Source

Environment Variables

Use environment variables for:

• Secrets — passwords, API keys, tokens (never commit these)
• Deployment overrides — values that differ between staging and production
• Container environments — Docker, Kubernetes, CI/CD pipelines

All SeqDesk environment variables use the SEQDESK_ prefix. See the full Environment Variables reference.

Config File

Use the config file for:

• Project-level settings — shared across the team, version-controlled
• Complete configuration — all sections in one structured file
• Reproducible deployments — check in alongside your infrastructure

SeqDesk searches for config files in this order:

1. seqdesk.config.json (recommended)
2. .seqdeskrc
3. .seqdeskrc.json

See the Config File Reference.

Database (Admin UI)

Use the Admin UI for:

• Runtime changes — adjust settings without restarting
• Non-technical admins — visual interface, no file editing
• Site branding — name, colors, logo, contact email

Settings changed through the Admin UI are stored in the database and take effect immediately for most values. Some settings require a server restart.

See Runtime Settings.

Viewing Configuration Status

Facility admins can check the active configuration and its sources at Admin → Settings or via the API endpoint:

GET /api/admin/config/status

The response includes:

• config — the resolved configuration (sensitive values are masked)
• sources — a mapping of each config path to its source (env, file, database, or default)
• filePath — path to the loaded config file, if found
• loadedAt — timestamp of when configuration was loaded

Best Practices

• Keep secrets in environment variables, never in config files or the database
• Version-control your config file — commit seqdesk.config.json alongside deployment scripts
• Use the Admin UI for day-to-day changes — it is the simplest path for routine adjustments
• Document overrides — if you use env vars to override config file values, document why