settings.json

Create a file (for example settings.json) to pre-configure your environment, then run an unattended install:

seqdesk -y --config ./settings.json

In interactive mode the installer asks for these values one by one. The config file lets you skip the prompts and automate the whole setup. The installer reads the JSON object at the top level, so most options are simple flat keys. Nested objects (such as pipelines.execution or bootstrap.users) and a few aliases are also accepted; see Flat and nested forms.

This is the same configuration the in-app Admin config builder produces; see Relationship to the admin config builder.

Before using unattended JSON on a server, confirm the installation prerequisites. Set databaseUrl when SeqDesk should use a database you already run; omit it and the installer resolves PostgreSQL itself — reusing a healthy local server, or creating and owning a private socket-only cluster under $HOME/.seqdesk/postgres as the (non-root) account running the install. Keep secrets out of any file you share publicly; see Handling secrets.

What is required

No single field is mandatory: the installer fills in sensible defaults for everything, so an empty {} config completes on any host where it can reuse or create a local PostgreSQL database. For a real deployment you normally set a few essentials.

When databaseUrl is set it must be a postgresql:// URL; SQLite and other schemes abort the install.

Minimal config

The essentials for a real server install:

{
  "nextAuthUrl": "https://seqdesk.example.org",
  "databaseUrl": "postgresql://seqdesk:replace-with-password@127.0.0.1:5432/seqdesk?schema=public",
  "sequencingDataDir": "/data/sequencing"
}

To skip pipelines entirely, add "pipelinesEnabled": false.

Download the minimal template: settings.min.json.

Full config

A current template covering the common sections. Everything here is optional on top of the minimal config; replace placeholder values, and prefer environment variables or CLI flags for the secrets called out below.

{
  "port": 8000,
  "nextAuthUrl": "https://seqdesk.example.org",
  "nextAuthSecret": "set-via-env-SEQDESK_NEXTAUTH_SECRET-or-replace",
  "anthropicApiKey": "set-via-env-ANTHROPIC_API_KEY-or-replace",
  "adminSecret": "set-via-env-SEQDESK_ADMIN_SECRET-or-replace",
 
  "databaseUrl": "postgresql://seqdesk:replace-with-password@127.0.0.1:5432/seqdesk?schema=public",
  "directUrl": "postgresql://seqdesk:replace-with-password@127.0.0.1:5432/seqdesk?schema=public",
 
  "sequencingDataDir": "/data/sequencing",
 
  "pipelinesEnabled": true,
  "pipelineRunDir": "/data/pipeline_runs",
  "pipelineDatabaseDir": "/data/pipeline_databases",
  "useSlurm": true,
  "slurmQueue": "cpu",
  "slurmCores": 4,
  "slurmMemory": "64GB",
  "slurmTimeLimit": 12,
  "slurmOptions": "--qos=standard",
  "condaPath": "/opt/miniconda3",
  "condaEnv": "seqdesk-pipelines",
  "nextflowProfile": "conda",
  "nextflowWeblogUrl": "https://seqdesk.example.org/api/pipelines/weblog",
  "weblogSecret": "set-via-env-SEQDESK_WEBLOG_SECRET-or-replace",
 
  "privatePipelines": {
    "metaxpath": {
      "repository": "hzi-bifo/MetaxPath-Nextflow",
      "ref": "main",
      "releaseTag": "latest",
      "packageUrl": "",
      "key": "set-via-env-SEQDESK_METAXPATH_KEY-or-replace",
      "sha256": ""
    }
  },
 
  "forms": {
    "order": "/opt/seqdesk/config/order-form.json",
    "study": "/opt/seqdesk/config/study-form.json"
  },
 
  "bootstrap": {
    "users": {
      "admin": {
        "email": "admin@example.org",
        "password": "set-via-env-or-replace-then-change-after-first-login",
        "firstName": "Site",
        "lastName": "Admin",
        "facilityName": "Example Sequencing Facility"
      }
    }
  },
 
  "site": { "name": "Example Sequencing Facility", "contactEmail": "support@example.org" },
  "auth": { "allowRegistration": false },
  "access": { "departmentSharing": true, "allowDeleteSubmittedOrders": false, "orderNotesEnabled": true },
  "ena": { "testMode": true, "username": "Webin-XXXXX", "password": "set-via-env-SEQDESK_ENA_PASSWORD-or-replace", "brokerAccount": false, "centerName": "Example Center" },
  "telemetry": { "enabled": false },
  "notifications": { "enabled": false }
}

Download the full template: settings.json, then edit it (or start from the minimal template above).

Field reference

Core and process

• port: HTTP port the app listens on. The installer also parses a port from nextAuthUrl when this is unset. CLI --port overrides.
• installDir: Target install directory (aliases seqdeskDir, dir). CLI --dir overrides.
• usePm2: Run the app under PM2 instead of the default process manager. CLI --use-pm2 / --no-pm2 override.

URLs and secrets

• nextAuthUrl: Recommended. Public base URL used for authentication callbacks (NEXTAUTH_URL). Defaults to http://localhost:8000, which breaks sign-in from other machines, so set your real URL.
• nextAuthSecret: Session-signing secret (NEXTAUTH_SECRET). Generated automatically when omitted. Secret.
• anthropicApiKey: Optional Anthropic API key for AI validation and extraction features. Secret.
• adminSecret: Secret protecting privileged and release-publishing endpoints. Secret.
• blobReadWriteToken: Vercel Blob token used by release-publishing scripts. Secret. Usually unset for normal facility installs.

Database

• databaseUrl: PostgreSQL connection string (DATABASE_URL). Omit it to let the installer reuse a local server or create and own a private socket-only cluster; set it for a managed, remote, or already-prepared database. An explicit value is authoritative and is never silently retargeted. Must be a postgresql:// URL; SQLite and other schemes are rejected. Secret.
• directUrl: Optional direct PostgreSQL connection used for Prisma migrations (DIRECT_URL). Falls back to databaseUrl when omitted. Secret.

Storage

• sequencingDataDir: Recommended. Root directory containing raw sequencing run folders (aliases sequencingDataPath, dataBasePath; nested site.dataBasePath). If omitted, set the data path later under Admin > Data Storage. CLI --data-path overrides.

Pipelines

• pipelinesEnabled: Master switch for pipeline support (aliases pipelineEnabled, nested pipelines.enabled). When unset, the installer auto-enables pipelines if any pipeline hint key is present (pipelineRunDir, pipelineDatabaseDir, useSlurm, condaPath, condaEnv, nextflowProfile, nextflowWeblogUrl, weblogSecret, or any privatePipelines.metaxpath value). A hint counts as present whenever the key has a value, so "useSlurm": false still turns pipelines on — set "pipelinesEnabled": false explicitly to skip pipeline setup entirely. Without any of these, a fresh install is core-only. CLI --with-pipelines / --without-pipelines override.
• pipelineRunDir: Directory for pipeline run output and work files. Use an absolute path. CLI --run-dir overrides.
• pipelineDatabaseDir: Shared root directory for large pipeline reference databases. CLI --pipeline-db-dir overrides.

Execution (local or Slurm):

• useSlurm: Submit pipeline jobs to Slurm; when false, pipelines run locally. If unset, it is derived from pipelines.execution.mode (slurm means true, local means false).
• slurmQueue: Slurm partition/queue (default cpu).
• slurmCores: CPU cores per Slurm job (default 4).
• slurmMemory: Memory per Slurm job, for example "64GB" (default 64GB).
• slurmTimeLimit: Maximum wall-clock hours per Slurm job (default 12).
• slurmOptions: Extra raw sbatch flags (QOS, account, gres, and so on; alias clusterOptions). There are no separate partition/account/gres/qos keys; everything extra goes here.
• condaPath: Path to the Conda/Miniconda base install used by pipelines.
• condaEnv: Conda environment name to activate (default seqdesk-pipelines).
• nextflowProfile: Optional Nextflow -profile override. SeqDesk pipeline execution is Conda-based; container profiles such as docker, singularity, apptainer, and podman are rejected by the runtime.
• nextflowWeblogUrl: Endpoint where Nextflow sends run progress events (alias weblogUrl).
• weblogSecret: Shared secret used to authenticate weblog requests. Secret.

Private pipeline package (MetaxPath):

• privatePipelines.metaxpath.repository: GitHub release repository. Defaults to hzi-bifo/MetaxPath-Nextflow.
• privatePipelines.metaxpath.ref: Source ref metadata. Defaults to main.
• privatePipelines.metaxpath.releaseTag: GitHub release tag to resolve, or latest.
• privatePipelines.metaxpath.packageUrl: Optional manual tarball URL. Leave blank to resolve the GitHub release asset automatically.
• privatePipelines.metaxpath.key: GitHub/package bearer token used to resolve and download the private package. Secret.
• privatePipelines.metaxpath.sha256: Optional manual tarball checksum. Leave blank to use the release asset digest automatically.

Advanced (nested only):

• pipelines.execution.pipelineOverrides: Per-pipeline execution defaults, keyed by pipeline id. Each override accepts mode (inherit, local, slurm), slurmQueue, slurmCores, slurmMemory, slurmTimeLimit, slurmOptions, and nextflowProfile.
• pipelines.execution.conda.cacheDir: Shared Nextflow conda cache directory so per-process environments are reused across runs.
• pipelines.mag.enabled / version / stubMode / skipProkka / skipConcoct: MAG pipeline toggles.

Seeded accounts

Optional. If you omit this section and the target database is empty, the installer seeds the published default accounts (admin@example.com / admin and user@example.com / user) that you must change immediately. Pre-create the first accounts so an unattended install is ready to log in to. Plaintext passwords are bcrypt-hashed during install and cleared from the written config; if you supply passwordHash, it takes precedence over password.

Two guards limit this. An account that already exists in the target database is never overwritten — its current password stays in force and the installer says so instead of printing one (see installing against a database that already had accounts). And the built-in default password is refused whenever this install named an account but no password for it, or the database was already configured by something before; the account is then simply not created. If you end up locked out either way, use seqdesk reset-password.

• bootstrap.users.admin.email, .password (or .passwordHash), .firstName, .lastName, .facilityName: Seeded facility-admin account.
• bootstrap.users.researcher.email, .password (or .passwordHash), .firstName, .lastName, .institution, .researcherRole: Optional seeded researcher account.

Form presets

Apply exported form-builder JSON during installation. The installer reads these files after migrations and seed:

• forms.order: JSON exported from Admin > Order Form > Import / Export.
• forms.study: JSON exported from Admin > Study Forms > Import / Export.

Equivalent top-level keys are also accepted: orderFormSettings / order_form_settings and studyFormSettings / study_form_settings. For command-line installs, use --order-form-settings and --study-form-settings. Use absolute paths so the installer can find the files regardless of the working directory.

Application settings

These nested sections are written into the runtime config and applied when the app starts. They are the same settings you can change later under Admin, so they are optional at install time.

• site.name, site.contactEmail: Facility display name and contact email.
• auth.allowRegistration: Whether users may self-register.
• access.departmentSharing, access.allowDeleteSubmittedOrders, access.allowUserAssemblyDownload, access.orderNotesEnabled, access.postSubmissionInstructions: User-facing permissions and sequencing order behavior.
• ena.testMode, ena.username, ena.password, ena.brokerAccount, ena.centerName: ENA Webin submission defaults. ena.password is a secret.
• telemetry.enabled, telemetry.endpoint, telemetry.intervalHours: Opt-in anonymous operational telemetry.
• notifications.enabled, notifications.provider, notifications.relayUrl, notifications.relayToken, notifications.inApp.enabled: Email and in-app notification relay. notifications.relayToken is a secret.
• sequencingFiles.extensions, .scanDepth, .ignorePatterns, .autoAssign, .simulationMode: File-discovery behavior.

auth.requireEmailVerification and auth.sessionTimeout are accepted by the configuration shape but are not enforced by the current authentication runtime. sequencingFiles.allowSingleEnd is currently forced on by the runtime. They are therefore omitted from the recommended template until their implementations change.

Handling secrets

Provide secrets through environment variables or CLI flags rather than committing them in a file you store or share:

The MetaxPath package URL and checksum can also be supplied as SEQDESK_METAXPATH_PACKAGE_URL and SEQDESK_METAXPATH_SHA256; they are manual overrides and are normally left unset so the GitHub release asset resolves automatically.

Flat and nested forms

Most options accept several spellings, resolved in order (the first value present wins). Flat top-level keys are the simplest and best-tested path; use nested objects for sections that have no flat equivalent (bootstrap.users, ena, site, auth, access, telemetry, notifications, sequencingFiles, pipelines.mag, and per-pipeline overrides). Where both exist they are interchangeable, for example:

• sequencingDataDir is the same as site.dataBasePath
• pipelineRunDir is the same as pipelines.execution.runDirectory
• useSlurm is the same as pipelines.execution.slurm.enabled

Booleans accept true/false as well as yes/no/1/0/on/off. Numeric fields like slurmCores, slurmTimeLimit, and port are only applied when greater than zero.

Validate and troubleshoot

Validate the file without printing its secrets:

node -e 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")); console.log("valid JSON")' \
  /etc/seqdesk/settings.json
chmod 600 /etc/seqdesk/settings.json

If the installer cannot find a config or form-preset file, use an absolute path; automation often starts in a different working directory. If a valid setting appears ignored, check for an explicit CLI flag or already-set SEQDESK_* environment variable, because those take precedence over JSON.

Inline --additional-setting path=value overrides are strings. Use --additional-settings-file when a boolean, number, array, or object must keep its JSON type.

For Neon or another pooled PostgreSQL service, use the pooled connection for databaseUrl and the provider’s direct connection for directUrl. Both must point at the same database and schema. Never paste either full URL into logs.

--reconfigure reapplies this configuration and deliberately skips the release download; it is not an application update. Adding --reseed-db explicitly runs migrations and seed against the configured database; take and verify a database backup before using it on an existing production instance. See Troubleshooting unattended installs for safe rerun, target-directory, CI-log, and database guidance.

Relationship to the admin config builder

The in-app Admin config import (under Infrastructure) accepts a subset of this same JSON, mapped to the same screens:

• Admin > Data Storage writes sequencingDataDir.
• Admin > Pipeline Runtime writes the execution settings: pipelineRunDir, useSlurm, slurmQueue, slurmCores, slurmMemory, slurmTimeLimit, slurmOptions, condaPath, condaEnv, nextflowProfile, nextflowWeblogUrl, weblogSecret, and pipelineOverrides.

So the JSON you hand-write for a file-based install is the same shape the admin builder produces. The file-based installer additionally accepts the install-time, database, auth, seeded-user, ENA, notification, telemetry, and private-pipeline keys above, which the in-app importer does not handle (it points you to the relevant Admin tabs instead).

Configure later in app

• Admin > Data Storage: Set the sequencing data base path.
• Admin > Pipeline Runtime: Configure run directory, Slurm or local mode, Conda, and Nextflow settings.
• Admin > Order Form / Study Forms: Import, export, or reset form-builder JSON.
• Reconfigure from JSON: Edit your config file and re-run the installer with --reconfigure. It reads the existing config to pre-fill defaults.