Prerequisites

SeqDesk runs on standard Linux servers and can also run as a local MacBook instance for development or evaluation. It needs Node.js/npm plus PostgreSQL 14 or newer. In most cases you do not have to supply a database: when the connection target is local, the installer first tries to reuse a running server, and otherwise creates and runs its own socket-only PostgreSQL cluster under ~/.seqdesk/postgres as your normal login user — no root, no sudo, and no launchd/systemd service. Pipeline execution is optional and adds Conda, Nextflow, and possibly Slurm requirements.

Required

What the installer checks

The guided command downloads the public installer over HTTPS. The installer then runs staged checks so failures that can be detected early happen before it downloads a release, replaces a target, or migrates anything.

The installer does not benchmark CPU, RAM, storage throughput, available capacity for sequencing data/reference databases/pipeline work, or scheduler capacity. It also does not validate your institution’s firewall policy, reverse proxy, TLS termination, backup strategy, or public-exposure safety. Those are deployment decisions, not properties the installer can infer.

seqdesk doctor is a post-install diagnostic, not a replacement for this preflight. It checks the installed layout and configuration, PostgreSQL reachability — over a Unix socket when the configured URL carries an absolute host= parameter, which is the normal shape for a SeqDesk-managed or socket-reused install, and over TCP otherwise — and optional application HTTP endpoints. It does not re-check the supported Node.js range, enforce the PostgreSQL major, size hardware/storage, or validate the complete pipeline toolchain. See seqdesk doctor for its exact checks.

While the install runs, the detailed narration of these checks goes to the installer log only — /tmp/seqdesk-install-<timestamp>.log, or the path you set in SEQDESK_LOG. Pass --verbose (or set SEQDESK_VERBOSE=1) to promote that diagnostic detail to the terminal as well.

Capacity planning (not enforced)

SeqDesk has no universal CPU/RAM minimum because the web application and bioinformatics workflows have very different resource profiles. Use these as planning starting points, not compatibility guarantees:

Keep sequencing data, pipeline work, results, and reference databases on storage with enough headroom and I/O performance for the facility’s workload. The install-directory disk check does not cover those separate filesystems.

Compatibility evidence

These two clean-install profiles are required on every pull request, main push, merge-queue candidate, and release:

The extended matrix runs weekly and when manually requested:

An extended row is compatibility evidence only when its individual job is green. The native Windows job verifies that the launcher rejects Windows with WSL guidance; it does not test a WSL installation. Real Slurm execution remains a separate private integration test. See the full compatibility statement  for the exact assertions and limitations.

PostgreSQL options

Use one of these approaches:

Running the installer as root (including sudo bash install.sh) disables the managed cluster: it refuses to create a PostgreSQL instance owned by root and tells you to rerun as a normal user or pass --database-url.

The application user does not need sudo after PostgreSQL is prepared. It only needs a valid connection string such as:

postgresql://seqdesk:<password>@127.0.0.1:5432/seqdesk?schema=public

A SeqDesk-managed cluster (or a reused local socket) never opens a TCP port, so its URL is socket-shaped instead. The installer generates it for you and stores it in the protected settings.json:

postgresql://seqdesk:<password>@localhost:5432/seqdesk?schema=public&host=%2FUsers%2Fyou%2F.seqdesk%2Fpostgres%2Fsocket

The database is not automatically isolated by install directory. If that URL already contains SeqDesk tables, a fresh application-directory install will connect to and migrate the existing data. The installer reports the PostgreSQL server version and warns when existing SeqDesk users/orders are detected. Use a different database or schema when you need a clean evaluation instance.

The SeqDesk-managed cluster

When the installer creates its own PostgreSQL, everything lives under SEQDESK_PG_HOME (default $HOME/.seqdesk/postgres, mode 0700) with data/, socket/, and server.log. Keep that path at 85 characters or fewer — the macOS Unix-socket path limit — or set a shorter SEQDESK_PG_HOME before installing.

The cluster is socket-only: listen_addresses is empty, pg_hba.conf rejects every host/hostssl line, and the socket directory is mode 0700, so nothing outside your account can reach it. Authentication is local peer and the cluster superuser is your own OS user.

It is deliberately not registered with launchd or systemd. Instead, the installation’s start.sh checks the cluster with pg_ctl status on every start and starts it when it is not running, so a PM2-resurrected app brings its own database up after a reboot. If the cluster cannot start, start.sh warns and names server.log.

Admin request for AlmaLinux/RHEL

You only need this when the host has no PostgreSQL server binaries (initdb, pg_ctl) and you cannot install them yourself. If those binaries are already present, SeqDesk creates and runs its own private cluster as your user and no admin request is needed — the minimal ask is then just sudo dnf install -y postgresql-server postgresql-contrib. If a full system server is what you want, send this to the server administrator and replace <password> with the value you want in DATABASE_URL:

Please prepare PostgreSQL for a local SeqDesk instance on this AlmaLinux/RHEL host.

Install and start PostgreSQL:

sudo dnf install -y postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

Create the SeqDesk role and database:

sudo -u postgres psql <<'SQL'
CREATE ROLE seqdesk LOGIN PASSWORD '<password>';
CREATE DATABASE seqdesk OWNER seqdesk;
SQL

Please make sure local password authentication from 127.0.0.1 works for:

postgresql://seqdesk:<password>@127.0.0.1:5432/seqdesk?schema=public

After the admin confirms, run:

npx -y seqdesk@latest --interactive --dir "$HOME/seqdesk"

Choose Existing/managed PostgreSQL in the wizard and paste the connection string the administrator prepared. This is a normal fresh install, so the target must not exist and --reconfigure must not be used.

Installer PostgreSQL bootstrap

The installer can perform the local PostgreSQL setup as a separate bootstrap step. This is only needed for a system PostgreSQL server, which requires sudo on Linux; a SeqDesk-managed private cluster needs no sudo and is created automatically during a normal install. On a fresh host with no existing install, --prepare-postgres needs the target connection string, so pass SEQDESK_DATABASE_URL (or --database-url); otherwise it exits with No DATABASE_URL found.

On macOS, run it as your normal login user — PostgreSQL setup never uses sudo there, and as root the installer refuses to create a cluster:

env SEQDESK_DATABASE_URL="postgresql://seqdesk:<password>@127.0.0.1:5432/seqdesk?schema=public" \
  npx -y seqdesk@latest -y --prepare-postgres --dir /path/to/seqdesk

On Linux, for a system PostgreSQL server:

sudo env PATH="$PATH" SEQDESK_DATABASE_URL="postgresql://seqdesk:<password>@127.0.0.1:5432/seqdesk?schema=public" \
  npx -y seqdesk@latest -y --prepare-postgres --dir /path/to/seqdesk

After preparing PostgreSQL for a fresh target, continue with the normal installation command and the same private connection string:

SEQDESK_DATABASE_URL="postgresql://seqdesk:<password>@127.0.0.1:5432/seqdesk?schema=public" \
  npx -y seqdesk@latest -y --dir /path/to/seqdesk

Do not add --reconfigure: that mode requires an existing SeqDesk installation directory. The normal fresh install applies migrations and seed data.

If you point --prepare-postgres --dir at an existing SeqDesk install, the URL is read from its protected configuration and the explicit SEQDESK_DATABASE_URL can be omitted. After preparation, resume that existing installation with:

npx -y seqdesk@latest -y --reconfigure --reseed-db --dir /path/to/seqdesk

Take and verify a database backup before using --reseed-db. If the existing database is already initialized and only configuration needs to be reapplied, omit --reseed-db.

If sudo does not preserve access to npx, install the SeqDesk launcher system-wide or ask the admin to run the SQL setup directly.

macOS prerequisites

For a local MacBook install, pin Node.js 24 with Homebrew:

brew install node@24
export PATH="$(brew --prefix node@24)/bin:$PATH"

For the local-database choice, the guided installer first reuses an already-running PostgreSQL 14–18 server: on 127.0.0.1:5432, on a local socket you own, or as an already-registered non-root Homebrew service. If none is available it installs the PostgreSQL server binaries with Homebrew and creates its own socket-only cluster under ~/.seqdesk/postgres (override with SEQDESK_PG_HOME), started with pg_ctl as your macOS login user. PostgreSQL setup on macOS always runs as your normal login user: do not use sudo, and do not run sudo brew services start for PostgreSQL — a service registered as a root LaunchDaemon is detected and refused with repair steps. Homebrew is required for this path; without it, supply --database-url instead.

Then run the downloaded guided installer—see the macOS install guide, which uses a local ~/seqdesk directory, port 8000, and local PostgreSQL.

Optional pipeline prerequisites

Pipeline support is optional and disabled on a fresh install unless a profile enables it. Add --with-pipelines only on hosts where SeqDesk should run or submit bioinformatics workflows.

For locked-down HPC systems, ask the admin which Conda path, Slurm partition, memory limits, and writable run directory should be used before creating the settings.json.