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.

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; the path must be 85 characters or shorter). 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 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 both the exact minimum boundary and the recommended current environment:

Both 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.

A broader weekly/manual matrix adds ARM64, macOS 15, 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

For the downloaded installer, npm launcher, piped fallback, or source install, start with the Quickstart troubleshooting checklist. 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