Installation

Install SeqDesk with a guided flow first, then move to unattended deployment as your environment standards solidify.

Use the downloaded public installer as the guided entry point. Saving it to a file keeps the prompts connected to your terminal and avoids a global npm installation.

What this section covers

An installation is three things the installer assembles for you, and it helps to know which is which before something goes wrong:

1. An install directory ($HOME/seqdesk in every example here). It holds settings.json — the runtime configuration, written chmod 600 — a start.sh wrapper, and a current/ symlink pointing at the release that is actually running. Updates and rollbacks re-point that symlink; your configuration at the root is not part of a release.
2. A PostgreSQL database. Usually one SeqDesk created and owns, under ~/.seqdesk/postgres, reachable only over a Unix socket. It has a separate lifetime from the install directory: replacing the directory does not touch the database, and installing again against the same database keeps every account and record in it.
3. Optionally, a pipeline toolchain — Conda, Java, Nextflow — installed only when you pass --with-pipelines. The core application does not need it.

Start with Quickstart if you just want it running, Prerequisites if this is a shared or locked-down server, and Unattended plus settings.json once you are deploying more than one host. When something breaks, Common problems is the symptom-to-fix table the installer’s own error messages link to; when the install is fine but nobody can sign in, go to Reset a password.

Most people

You need Node.js 22.13.0–22.x or Node.js 24.x. You do not need to install, start, or configure PostgreSQL yourself: if the installer finds no local server it can safely reuse, it creates and starts its own private PostgreSQL cluster under ~/.seqdesk/postgres (relocate it with SEQDESK_PG_HOME, keeping that path at 78 characters or fewer — see the SeqDesk-managed cluster). Pass --database-url "postgresql://..." only when you want SeqDesk to use a database you already run. Then:

curl -fsSLo /tmp/seqdesk-install.sh https://seqdesk.org/install.sh &&
bash /tmp/seqdesk-install.sh --interactive --dir "$HOME/seqdesk"

The wizard asks two things — which database to use and which administrator account to create — and the run ends with a completion summary containing the browser URL (http://127.0.0.1:8000 unless you set --nextauth-url), the install directory, and any password it generated. Open that URL, sign in with the administrator account you just created, and continue with First Login & Setup. That is the whole path for an evaluation; everything below is reference.

To evaluate without installing anything, open demo.seqdesk.org . It creates a disposable, pre-populated workspace with orders, studies, samples, metadata, read records, and inspectable example pipeline results. Facility-admin pages are read-only; downloads, external ENA submission, and pipeline execution are disabled on that shared service for safety.

For a local evaluation with generated files, configure a writable data path and then use Admin → Settings → Demo data, or run:

seqdesk storage configure "$HOME/seqdesk/data"
seqdesk demo-data status
seqdesk demo-data install

This creates two studies, four orders, samples, metadata, read rows, and deterministic synthetic gzipped FASTQ files. See Example Data & Provenance for contents, removal, public accessions, and the inputs used by pipeline CI.

The guided installer checks prerequisites first, then resolves PostgreSQL on both macOS and Linux without asking you to prepare anything: it reuses a healthy server on the configured connection or a local Unix socket it can administer, starts an already-registered but idle Homebrew service on macOS, and otherwise provisions its own socket-only cluster as your normal user — no sudo -v priming and no brew services start postgresql. Run the installer as a normal (non-root) user; on Linux, sudo is only needed to install the PostgreSQL server package when it is absent, or to administer a pre-existing system PostgreSQL, and on macOS the installer never uses sudo for PostgreSQL at all. You can still supply your own connection string via --database-url. It then applies migrations and prints the login URL when it finishes. It installs the core application by default; use --with-pipelines to opt into Conda and Nextflow provisioning. It hard-stops for an unsupported Node.js version, missing release tools, an unwritable or undersized install target, a checksum mismatch, or a database connection/write/migration failure. Untested Linux distributions and CPU architectures produce warnings. CPU/RAM sizing, sequencing-data and pipeline storage, network exposure, TLS, and production Slurm capacity remain operator decisions. Note that SeqDesk binds 0.0.0.0 (all interfaces) by default — set SEQDESK_BIND_HOST=127.0.0.1 at install or start time to restrict it to localhost.

PostgreSQL 14+ is the enforced baseline: when the installer adopts an existing Unix socket it asserts server_version_num >= 140000 and refuses anything older, and it rejects SQLite (file:) URLs outright. A cluster SeqDesk creates for itself is socket-only — it opens no TCP port, is peer-authenticated for the user who owns it, and is not registered with launchd or systemd; the install directory’s start.sh starts it before the app, so the database returns after a reboot. The prerequisite check matrix explains every automatic check and the remaining manual responsibilities. For the full walkthrough see Quickstart; for the PostgreSQL options (SeqDesk-managed private instance, reused local server, managed/remote URL) see Prerequisites. Platform-specific commands are in the Linux and macOS guides.

Continuously tested environments

SeqDesk continuously installs the same checksum-verified candidate release on three required profiles — the exact minimum boundary, the recommended current environment, and macOS:

All three jobs install through the candidate npm launcher, migrate a fresh database, boot the packaged application, and verify setup and authentication endpoints. They run on pull requests, main pushes, merge-queue candidates, and releases, and a single aggregate gate fails unless the candidate build and all three installs succeed.

A broader weekly/manual matrix adds ARM64 Linux, Intel macOS, Debian 12, Rocky Linux 9, PostgreSQL 15–18, and a packaged pipeline smoke test. Those combinations count as demonstrated only when their individual jobs are green. See the Reviewer Installation Matrix  and the complete compatibility statement .

Compare installation methods

Every method boots the same SeqDesk app — pick one by your scenario. For most users, the downloaded guided installer is the recommended path.

When an installation fails

Start with Common problems — a symptom-to-fix table, and the page the installer’s own Troubleshooting: links point to. For the downloaded installer, npm launcher, piped fallback, or source install, the Quickstart troubleshooting checklist goes into more detail. Re-run the installer with --verbose to print the diagnostic detail that otherwise goes only to the install log ($SEQDESK_LOG, by default /tmp/seqdesk-install-*.log). The Linux, macOS, AWS EC2, and Vercel + Neon guides keep their platform-specific checks beside the relevant install steps. On a completed host installation, run seqdesk doctor before changing files or recreating a database.

Recommended Path