Infrastructure JSON

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

seqdesk -y --config ./infrastructure-setup.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. The databaseUrl must point to an existing PostgreSQL database unless the installer can bootstrap local PostgreSQL with sudo. Keep secrets out of any file you share publicly; see Handling secrets.

What is required

No single field is strictly mandatory: the installer fills in sensible defaults for everything, so an empty {} config will even complete on a host where it can 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: infrastructure-setup.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, "requireEmailVerification": true, "sessionTimeout": 24 },
  "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: infrastructure-setup.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 --install-dir / --dir override.
• 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: Required in practice. PostgreSQL connection string (DATABASE_URL). If omitted, the installer tries to create and use a local PostgreSQL database and aborts if it cannot. 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). Set it to false to skip pipeline setup entirely. 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: Nextflow -profile to use (conda, docker, singularity).
• 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, the installer seeds default accounts (admin@example.com / admin) that you must change after first login. 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.

• 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, auth.requireEmailVerification, auth.sessionTimeout (hours): Account and session policy.
• access.departmentSharing, access.allowDeleteSubmittedOrders, access.allowUserAssemblyDownload, access.orderNotesEnabled, access.postSubmissionInstructions: User-facing permissions and 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, .allowSingleEnd, .ignorePatterns, .autoAssign, .simulationMode: File-discovery behavior.

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.

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.