Config File Reference

The settings.json file provides project-level configuration in a single structured JSON file. It is the recommended way to manage non-secret settings.

File Discovery

SeqDesk searches for config files in the project root (same directory as package.json) in this order:

settings.json (recommended)
seqdesk.config.json (legacy/development fallback)
.seqdeskrc
.seqdeskrc.json

The first file found is used. If no config file exists, only environment variables, database settings, and built-in defaults apply.

Older installs may still keep their runtime config under the legacy seqdesk.config.json filename. SeqDesk continues to read it as a fallback, so existing deployments keep working — no rename is required.

Complete Structure


{
  "app": {
    "port": 8000
  },
 
  "site": {
    "name": "My Sequencing Facility",
    "dataBasePath": "/mnt/sequencing/data",
    "contactEmail": "facility@example.com"
  },
 
  "pipelines": {
    "enabled": true,
    "databaseDirectory": "/mnt/seqdesk/pipeline-databases",
    "execution": {
      "mode": "local",
      "runDirectory": "./pipeline_runs",
      "conda": {
        "path": "/opt/conda",
        "environment": "seqdesk-pipelines"
      },
      "slurm": {
        "enabled": false,
        "queue": "cpu",
        "cores": 4,
        "memory": "64GB",
        "timeLimit": 12,
        "options": ""
      },
      "pipelineOverrides": {
        "mag": {
          "mode": "slurm",
          "slurm": {
            "queue": "long",
            "cores": 16,
            "memory": "128GB",
            "timeLimit": 48
          }
        },
        "metaxpath": {
          "mode": "slurm"
        }
      }
    },
    "mag": {
      "enabled": true,
      "version": "3.4.0",
      "stubMode": false,
      "skipProkka": true,
      "skipConcoct": true
    }
  },
 
  "ena": {
    "testMode": true,
    "username": "",
    "password": "",
    "brokerAccount": false,
    "centerName": ""
  },
 
  "sequencingFiles": {
    "extensions": [".fastq.gz", ".fq.gz", ".fastq", ".fq"],
    "scanDepth": 2,
    "ignorePatterns": ["**/tmp/**", "**/undetermined/**"],
    "autoAssign": false,
    "activeWriteMinAgeMs": 60000,
    "simulationMode": "auto",
    "simulationTemplateDir": "/opt/seqdesk/simulation-templates"
  },
 
  "access": {
    "departmentSharing": false,
    "allowDeleteSubmittedOrders": false,
    "allowUserAssemblyDownload": false,
    "orderNotesEnabled": true,
    "postSubmissionInstructions": ""
  },
 
  "auth": {
    "allowRegistration": true
  },
 
  "moduleSettings": {
    "account-validation": {
      "allowedDomains": ["example.org"],
      "enforceValidation": false
    },
    "billing-info": {
      "pspEnabled": false,
      "costCenterEnabled": false
    }
  },
 
  "telemetry": {
    "enabled": false,
    "endpoint": "https://seqdesk.org/api/telemetry/heartbeat",
    "intervalHours": 24
  },
 
  "notifications": {
    "enabled": false,
    "inApp": {
      "enabled": true
    },
    "provider": "seqdesk-relay",
    "relayUrl": "https://seqdesk.org/api/notifications/relay",
    "events": {
      "order": {
        "submitted": true,
        "statusChanged": true,
        "samplesSent": true
      },
      "ticket": {
        "created": true,
        "reply": true
      }
    },
    "userDefaults": {
      "orders": true,
      "support": true
    }
  },
 
  "runtime": {
    "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",
    "nextAuthUrl": "http://localhost:8000",
    "nextAuthSecret": "your-secret-here"
  }
}

Section Reference

`app` — Application Runtime

Key	Type	Default	Description
`port`	integer	`8000`	App listen port for generated start scripts

`site` — Facility Information

Key	Type	Default	Description
`name`	string	`"SeqDesk"`	Display name shown in the UI
`dataBasePath`	string	`"./data"`	Base directory for sequencing data
`contactEmail`	string	—	Contact email shown to researchers

`pipelines` — Pipeline Configuration

Key	Type	Default	Description
`enabled`	boolean	`false`	Master switch for pipeline features
`databaseDirectory`	string	`""`	Optional shared root directory for large pipeline database assets

`pipelines.execution` — Execution Settings

Key	Type	Default	Description
`mode`	`"local"` \| `"slurm"`	`"local"`	Where pipelines run
`runDirectory`	string	`"./pipeline_runs"`	Output directory
`pipelineOverrides`	object	`{}`	Per-pipeline execution defaults keyed by pipeline ID

`pipelines.execution.conda` — Conda Settings

Key	Type	Default	Description
`path`	string	`"/opt/conda"`	Conda installation path
`environment`	string	—	Environment name

`pipelines.execution.slurm` — SLURM Settings

Key	Type	Default	Description
`enabled`	boolean	`false`	Submit jobs to SLURM
`queue`	string	`"cpu"`	Partition/queue name
`cores`	integer	`4`	CPUs per job
`memory`	string	`"64GB"`	Memory per job
`timeLimit`	integer	`12`	Time limit (hours)
`options`	string	`""`	Additional SLURM options

`pipelines.execution.pipelineOverrides` — Per-Pipeline Runtime Policy

Each override is keyed by pipeline ID. Use this to keep global execution local while sending large workflows such as mag or metaxpath to SLURM.

Key	Type	Description
`mode`	`"inherit"` \| `"local"` \| `"slurm"`	Execution target for this pipeline
`slurm`	object	Optional per-pipeline queue, cores, memory, time limit, and options
`nextflowProfile`	string	Optional Conda-compatible Nextflow profile for this pipeline

SeqDesk uses Conda-based pipeline execution. Container profiles such as docker, singularity, apptainer, and podman are rejected when a run starts.

`pipelines.mag` — MAG Pipeline

Key	Type	Default	Description
`enabled`	boolean	`true`	Enable nf-core/mag
`version`	string	`"3.4.0"`	Pipeline version
`stubMode`	boolean	`false`	Test mode (no real analysis)
`skipProkka`	boolean	`true`	Skip Prokka annotation
`skipConcoct`	boolean	`true`	Skip CONCOCT binning

`ena` — ENA Submission

Key	Type	Default	Description
`testMode`	boolean	`true`	Use test server
`username`	string	—	Webin username
`password`	string	—	Webin password
`brokerAccount`	boolean	`false`	Webin account has ENA broker permissions
`centerName`	string	`""`	Submission center name

Avoid storing ENA credentials in the config file. Use environment variables (SEQDESK_ENA_USERNAME, SEQDESK_ENA_PASSWORD) or the Admin UI instead.

`sequencingFiles` — File Discovery

Key	Type	Default	Description
`extensions`	string[]	`[".fastq.gz", ".fq.gz", ".fastq", ".fq"]`	Allowed file extensions
`scanDepth`	integer	`2`	Directory scan depth (1–10)
`ignorePatterns`	string[]	`["/tmp/", "/undetermined/"]`	Glob patterns to skip
`autoAssign`	boolean	—	Automatically link discovered files to samples when names match
`activeWriteMinAgeMs`	integer	—	Minimum file age (ms) for active-write stability checks
`simulationMode`	`"auto"` \| `"synthetic"` \| `"template"`	`"auto"`	Read-simulation mode (auto uses templates if available)
`simulationTemplateDir`	string	—	Directory of realistic FASTQ pairs for template-based simulation

`access` — Researcher Access Policy

Key	Type	Default	Description
`departmentSharing`	boolean	—	Allow users to share submitted sequencing orders within their department
`allowDeleteSubmittedOrders`	boolean	—	Allow users to delete submitted sequencing orders
`allowUserAssemblyDownload`	boolean	—	Allow users to download assembly outputs
`orderNotesEnabled`	boolean	—	Enable sequencing order notes/comments
`postSubmissionInstructions`	string	—	Facility instructions shown after sequencing order submission

`auth` — Authentication

Key	Type	Default	Description
`allowRegistration`	boolean	`true`	Public registration enabled

The configuration shape still accepts auth.requireEmailVerification, auth.sessionTimeout, and sequencingFiles.allowSingleEnd for compatibility, but the current runtime does not enforce the first two and currently forces single-end support on. They are omitted from recommended examples until those implementations change.

`moduleSettings` — Optional Module Settings

Settings for optional modules, keyed by module id.

`moduleSettings.account-validation`

Key	Type	Description
`allowedDomains`	string[]	Email domains accepted for automatic account validation
`enforceValidation`	boolean	Require allowed-domain validation for new accounts

`moduleSettings.billing-info`

Key	Type	Description
`pspEnabled`	boolean	Enable PSP (project) number capture
`pspPrefixRange`	object	`{ min, max }` range for the PSP prefix
`pspMainDigits`	integer	Number of main PSP digits
`pspSuffixRange`	object	`{ min, max }` range for the PSP suffix
`pspExample`	string	Example PSP shown in the form
`costCenterEnabled`	boolean	Enable cost-center capture
`costCenterPattern`	string	Regex the cost center must match
`costCenterExample`	string	Example cost center shown in the form

`telemetry` — Operational Telemetry

Key	Type	Default	Description
`enabled`	boolean	`false`	Opt-in anonymous heartbeat reporting
`endpoint`	string	`https://seqdesk.org/api/telemetry/heartbeat`	Heartbeat URL
`intervalHours`	integer	`24`	Minimum hours between automatic heartbeats

See Operational Telemetry for what’s reported and how to opt out.

`notifications` — Notifications

Controls the in-app notification panel and the optional hosted email relay.

Key	Type	Default	Description
`enabled`	boolean	`false`	Master switch for the hosted SeqDesk email notification relay
`inApp.enabled`	boolean	`true`	Master switch for the in-app notification panel/channel
`provider`	`"seqdesk-relay"`	`"seqdesk-relay"`	Notification provider (only the hosted relay is supported)
`relayUrl`	string	`https://seqdesk.org/api/notifications/relay`	Hosted relay endpoint
`relayToken`	string	—	Scoped notification relay token — set via env, never committed
`events`	object	(all on)	Which events trigger notifications
`userDefaults`	object	`{ orders, support }`	Default per-user opt-in for `orders` and `support` channels

`notifications.events` — Event Toggles

Key	Type	Default	Description
`order.submitted`	boolean	`true`	Notify when a sequencing order is submitted
`order.statusChanged`	boolean	`true`	Notify when a sequencing order status changes
`order.samplesSent`	boolean	`true`	Notify when samples are marked sent
`ticket.created`	boolean	`true`	Notify when a support ticket is created
`ticket.reply`	boolean	`true`	Notify on a ticket reply

The relay token is a secret. Set relayToken through SEQDESK_NOTIFICATION_RELAY_TOKEN — never commit it to a config file. It is masked in /api/admin/config/status responses.

`runtime` — Application Runtime

These values are applied to process.env at startup if the corresponding environment variable is not already set.

Key	Maps To	Description
`databaseUrl`	`DATABASE_URL`	PostgreSQL runtime connection string
`directUrl`	`DIRECT_URL`	Direct PostgreSQL connection for Prisma migrations
`nextAuthUrl`	`NEXTAUTH_URL`	NextAuth.js callback URL
`nextAuthSecret`	`NEXTAUTH_SECRET`	Session signing secret
`anthropicApiKey`	`ANTHROPIC_API_KEY`	API key for AI validation/extraction routes
`adminSecret`	`ADMIN_SECRET`	Release publishing admin secret used by scripts
`blobReadWriteToken`	`BLOB_READ_WRITE_TOKEN`	Vercel Blob token for release publishing scripts
`updateServer`	`SEQDESK_UPDATE_SERVER`	Update server URL

Validation

The config system validates:

The file must be valid JSON
site.dataBasePath must be a string
pipelines.execution.mode must be local or slurm
ena.testMode must be a boolean
sequencingFiles.scanDepth must be an integer between 1 and 10

Invalid values are logged as warnings and the corresponding default is used instead.

Config File Reference

File Discovery

Complete Structure

Section Reference

app — Application Runtime

site — Facility Information

pipelines — Pipeline Configuration

pipelines.execution — Execution Settings

pipelines.execution.conda — Conda Settings

pipelines.execution.slurm — SLURM Settings

pipelines.execution.pipelineOverrides — Per-Pipeline Runtime Policy

pipelines.mag — MAG Pipeline

ena — ENA Submission

sequencingFiles — File Discovery

access — Researcher Access Policy

auth — Authentication

moduleSettings — Optional Module Settings

moduleSettings.account-validation

moduleSettings.billing-info

telemetry — Operational Telemetry

notifications — Notifications

notifications.events — Event Toggles

runtime — Application Runtime