Unattended + Reconfigure

Install the launcher once, then use -y for non-interactive mode and pass your JSON with --config.

npm i -g seqdesk@latest
seqdesk -y --config ./settings.json

The seqdesk launcher is the supported entry point. It downloads and executes the public installer script internally.

Confirm the host meets the installation prerequisites before running unattended installs. In particular, you usually do not have to supply a database at all: run the installer as a normal, non-root user and it reuses a healthy local PostgreSQL 14+ server it can administer, or creates and owns a private, socket-only cluster under $HOME/.seqdesk/postgres. sudo is only required on Linux to install the PostgreSQL server package when it is absent, or to administer a pre-existing system server that SeqDesk adopts. Do not run the installer as root (including sudo bash install.sh): it refuses to create a cluster owned by root and then requires an explicit --database-url instead.

You can also download the template we host and point the installer at a remote URL directly:

wget https://seqdesk.org/settings.json -O settings.json

seqdesk -y --config https://seqdesk.org/settings.json

To re-apply changed JSON values to an existing install in place:

seqdesk -y --reconfigure --config ./settings.json

Reconfigure updates keys present in your JSON. Omitted keys keep their current values.

Reconfigure skips database migrations and seeding by default to preserve existing data. If you explicitly want to run migrations and seed, use:

seqdesk -y --reconfigure --reseed-db --config ./settings.json

Path reminder: local --config and default ./seqdesk are resolved from your current working directory. Use absolute paths in automation. For a system location, have an administrator prepare a parent owned by the non-root SeqDesk service account, then use a new child as --dir; see Linux production directory setup.

When SeqDesk provisions its own PostgreSQL, the cluster is created under $HOME/.seqdesk/postgres for the account running the installer, not under --dir. Set SEQDESK_PG_HOME to place it elsewhere, for example on the same volume as the install root, and keep that path at 85 characters or shorter: longer paths exceed the Unix-socket limit and the installer aborts. The cluster is socket-only, opens no TCP port, and is not registered with systemd or launchd; <dir>/start.sh starts it before the app, so the process manager resurrecting start.sh is what brings the database back after a reboot.

Installing over an existing directory

A fresh install refuses to overwrite an existing target directory. In interactive mode it asks Backup and replace?; with -y it aborts instead, so an automated run never clobbers a directory silently.

Pass --overwrite-existing (or set SEQDESK_OVERWRITE_EXISTING=1) to let an unattended install replace an existing directory. The existing directory is moved to <dir>.backup.<timestamp> and a fresh install proceeds:

seqdesk -y --dir /opt/seqdesk --overwrite-existing

This keeps the previous install as a timestamped backup rather than deleting it. If the new install fails before it activates, the installer automatically restores the backup (or prints the exact restore command), so a failed run never leaves the host without a working install. To reapply configuration to an existing install without re-extracting it, use --reconfigure instead.

Preload form builders

Sequencing order and study form builders can be exported from an existing SeqDesk instance as JSON, then applied during install. This is useful when a facility wants a new instance to start with the approved sequencing order form and study metadata form already configured.

seqdesk -y \
  --config ./settings.json \
  --order-form-settings /absolute/path/order-form.json \
  --study-form-settings /absolute/path/study-form.json

The same values can be passed with environment variables:

export SEQDESK_ORDER_FORM_SETTINGS="/absolute/path/order-form.json"
export SEQDESK_STUDY_FORM_SETTINGS="/absolute/path/study-form.json"
 
seqdesk -y --config ./settings.json

The installer applies these files after database migration and seed. The JSON files should be the exports from Admin > Order Form > Import / Export and Admin > Study Forms > Import / Export.

Troubleshooting

Unattended runs should fail closed: keep the launcher exit code, retain the protected installer log, and treat seqdesk doctor as a post-install gate. Do not print settings files or database URLs into CI logs.

The config file is not found or cannot be downloaded

Relative config, install, and form-preset paths are resolved from the process working directory. Cron, CI, Puppet, and systemd may use a different directory than your interactive shell, so use absolute paths:

seqdesk -y \
  --config /etc/seqdesk/settings.json \
  --dir /srv/seqdesk/app \
  --run-doctor

For a remote config, test the same URL from the deployment host:

curl -fsSL https://example.org/seqdesk/settings.json -o /tmp/seqdesk-settings.json

An authenticated hosted profile must use --profile plus --profile-code. Do not combine --profile and --config.

JSON parsing fails or a value appears to be ignored

Validate local JSON before the install:

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

Use the fields and types from the settings.json reference. Explicit CLI flags and already-set SEQDESK_* environment variables take precedence over the base config. --additional-settings-file and --additional-setting modify that config before it is loaded, while an explicit flag still wins.

The target directory already exists

Choose the operation intentionally:

• New host: use a new --dir.
• Existing SeqDesk configuration: use --reconfigure --dir <existing-root>.
• Intentional replacement: use --overwrite-existing; the installer moves the old target to a timestamped backup and restores it automatically if activation fails.

--reconfigure reapplies configuration and skips release download. It is not an application update and it does not replace the active release. Do not add --overwrite-existing merely to make a retry continue.

PostgreSQL is unreachable

An unattended run does not need a database URL at all: with none supplied the installer reuses a healthy local server or provisions its own socket-only cluster under $HOME/.seqdesk/postgres. Supply a valid PostgreSQL URL in the config, with --database-url, or through SEQDESK_DATABASE_URL only when you want a specific — usually remote or managed — database. An explicit URL is then authoritative: if it is unreachable the installer reports the error rather than silently building a different database behind your back. SQLite and any other non-postgres(ql):// URL is rejected outright, and supplying DIRECT_URL without DATABASE_URL is a hard error. For a managed/pooled database, supply the migration connection as DIRECT_URL too. Follow the specific DNS, timeout, authentication, database, role, SSL, or write-permission error printed by the installer; the Quickstart database checklist has safe host-side checks.

A CI run fails or is interrupted

The installer exits non-zero for a failed gate and prints its protected log path. If you pipe output through tee, enable pipefail so CI keeps that exit status:

set -o pipefail
umask 077
seqdesk -y \
  --config /etc/seqdesk/settings.json \
  --dir /srv/seqdesk/app \
  --run-doctor 2>&1 | tee /absolute/private/path/seqdesk-provision.log

Redact passwords, full PostgreSQL URLs, profile codes, and tokens before sharing either log. After fixing the reported cause, rerun the same operation; do not delete the database or an automatically restored backup. For generic Node.js, disk, permission, download, and process-manager failures, use the Quickstart troubleshooting checklist.

Full installer flag reference

Every flag accepted by the seqdesk npm launcher. Most flags have a matching SEQDESK_* environment variable; see Environment Variables for the installer-only variables. Any unrecognised option is fatal: the installer prints Unknown option: <flag> followed by the usage and exits 1.

Mode and target

Configuration source

Hosted install profile

Infrastructure overrides

Secrets

Pipelines

Process management

Diagnostics

Form presets