Linux Install

This guide covers the recommended guided flow — download https://seqdesk.org/install.sh and run it with --interactive — on Ubuntu/Debian and RHEL-family systems such as AlmaLinux and Rocky Linux. npx -y seqdesk@latest and a globally installed seqdesk fetch and run the same script, so the flags below apply unchanged to all three entry points. Use the home-directory example for a local evaluation. For a shared or production server, prepare a service-owned parent directory, database, firewall, and TLS reverse proxy before making SeqDesk reachable from another machine.

Quick start

SeqDesk requires Node.js >=22.13.0 <23 or >=24 <25; Node.js 24 is recommended. First check the active commands:

command -v node npm
node --version
npm --version

If Node.js is missing, these Node.js 22 commands match the installation hints printed by the SeqDesk installer.

On Ubuntu or Debian:

sudo apt-get update
sudo apt-get install -y curl tar coreutils
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

On AlmaLinux, Rocky Linux, RHEL, or another dnf-based system:

sudo dnf install -y curl tar coreutils
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

Confirm that node --version is at least 22.13.0. Then download the current installer:

curl -fsSLo /tmp/seqdesk-install.sh https://seqdesk.org/install.sh

For a small local evaluation you normally need no sudo at all. When the PostgreSQL server programs (initdb, pg_ctl) are present, SeqDesk creates and starts its own socket-only cluster under $HOME/.seqdesk/postgres, owned by your login user:

SEQDESK_BIND_HOST=127.0.0.1 bash /tmp/seqdesk-install.sh --interactive \
  --dir "$HOME/seqdesk"

Refresh your sudo credential with sudo -v beforehand only in the two cases where the installer needs a privileged command: installing the PostgreSQL server package when it is missing, and creating the SeqDesk role and database inside a pre-existing system PostgreSQL server (sudo -n -u postgres psql). Those operations always use non-interactive sudo -n, so they never block on a password prompt; sudo -v lets them reuse your recently authenticated sudo session. Skip it when you will select an existing or managed PostgreSQL database in the wizard.

The wizard creates the first administrator account. Fresh installs skip Conda, Java, and Nextflow; add --with-pipelines on a supported host that should execute pipelines.

The target must be new. If ~/seqdesk is already an installed instance, use --reconfigure only to reapply configuration. If it is unrelated, choose another directory. --overwrite-existing backs up and replaces the target and should only be used intentionally.

How SeqDesk gets a PostgreSQL database

In most cases you do not have to supply one. When the target database is local, the installer tries, in order:

1. reuse a healthy server already answering at 127.0.0.1:5432;
2. reuse a local Unix socket it can administer — the socket file must be owned by your OS user and you must be a PostgreSQL 14+ superuser there;
3. otherwise create its own cluster with initdb under ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres} (data/, socket/, server.log, mode 0700).

The cluster SeqDesk creates is socket-only: listen_addresses = '', unix_socket_permissions = 0700, and every host/hostssl line in pg_hba.conf is rejected, so it never opens TCP port 5432. Its connection URL therefore carries a host=<socket directory> parameter. Set SEQDESK_PG_HOME to relocate it; the socket directory path must stay at or below 85 characters. Re-running the installer starts an existing cluster and never rebuilds it.

SeqDesk refuses to create a cluster owned by root, so do not run the installer under sudo. Rerun as a normal user, or pass --database-url for a database you manage yourself. An explicit --database-url (or SEQDESK_DATABASE_URL) is never silently retargeted; SQLite (file:) URLs are rejected.

Production directory and network

An ordinary user normally cannot create /opt/seqdesk. Do not run the entire installer as root just to bypass that permission. Prepare a parent owned by the account that will run SeqDesk, then install into a new child directory:

sudo install -d -o "$USER" -g "$(id -gn)" /srv/seqdesk
bash /tmp/seqdesk-install.sh --interactive --dir /srv/seqdesk/app

For a dedicated service account, substitute that account and group in the install -d command and run the SeqDesk installer as that user. The final target (/srv/seqdesk/app above) must not already exist.

Installed SeqDesk listens on port 8000 by default. The default bind host is 0.0.0.0, so SeqDesk answers on every interface unless you set SEQDESK_BIND_HOST=127.0.0.1. The chosen value is persisted in $SEQDESK_DIR/.seqdesk-bind-host and re-applied by start.sh on every boot, so set it during the install (or with --reconfigure) rather than exporting it by hand. A server intended for other users needs an explicit hostname in NEXTAUTH_URL, a firewall that limits access, and normally a TLS reverse proxy. Do not expose port 5432 or published bootstrap credentials to the public internet. See Settings JSON before automating a production deployment.

Migrating from previous Linux commands

Older instructions used a bare seqdesk command or invoked install.sh directly into /opt/seqdesk. You do not need to recreate PostgreSQL or reinstall an existing SeqDesk instance just because the recommended launcher command changed.

First identify the installation directory and active process as the same Linux user that originally installed SeqDesk:

command -v node npm seqdesk
node --version
pm2 status

The old default target was ./seqdesk relative to the directory from which the installer was run, so do not assume the existing instance is in /opt. Keep its current directory and database. Upgrade the launcher, then run the read-only health check against the installation root:

npm i -g seqdesk@latest
seqdesk doctor --dir "/absolute/path/to/your/seqdesk"

If you need to change the bind address, URL, or another configuration value, use reconfigure mode:

seqdesk -y --reconfigure \
  --dir "/absolute/path/to/your/seqdesk"
seqdesk doctor --dir "/absolute/path/to/your/seqdesk"

--reconfigure skips the release download and is not an application update. Update the installed application from Admin → Settings → Software Updates. See Manual Update & Rollback for the update, backup, and rollback flow. Do not run a fresh installation over the existing directory.

SeqDesk supports PostgreSQL 14–18. If you independently decide to change the PostgreSQL major version, make and verify a database backup first, then use PostgreSQL’s major-version upgrade procedure . Do not delete or reinitialize the existing data directory as a repair step.

Verify and sign in

The completion summary prints the exact browser URL, installation directory, and PM2 command. For the local evaluation above:

npx -y seqdesk@latest doctor --dir "$HOME/seqdesk" --url http://127.0.0.1:8000
curl -fsS http://127.0.0.1:8000/api/setup/status

Open http://127.0.0.1:8000 and sign in with the administrator account created by the guided wizard. If you used unattended defaults instead, change or remove the published bootstrap accounts immediately before allowing another machine to reach the service.

Troubleshooting

Node.js is missing or unsupported

Check which executable your shell is actually using:

command -v node npm
node --version
npm --version

SeqDesk accepts Node.js 22.13.0 through 22.x and Node.js 24.x. It rejects Node 23, 25, and newer majors until they are explicitly supported. Install a supported version with the Ubuntu/Debian or RHEL-family commands above, or select Node.js 24 with your existing version manager, then start a fresh shell and rerun the installer.

npm reports EACCES

An EACCES error from npm i -g means the active global npm prefix is not writable. Do not run the whole SeqDesk installation as root. Use a Node.js version manager, ask an administrator to install the launcher globally, or launch the current package without a global install:

SEQDESK_BIND_HOST=127.0.0.1 npx -y seqdesk@latest --interactive \
  --dir "$HOME/seqdesk"

Add sudo -v beforehand only when the PostgreSQL server package still has to be installed on this host, or when the installer must create the SeqDesk role inside an existing system PostgreSQL service. It is unnecessary when you will provide an existing or managed PostgreSQL URL, and when the PostgreSQL server programs are already installed — SeqDesk then creates and starts its own cluster under ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres} without any privileged command.

No interactive TTY detected

The guided wizard needs a real terminal. Run the downloaded installer or the npx command above directly in an interactive SSH or terminal session, rather than through a background job, redirected standard input, or a CI runner.

For intentional automation, use -y (or SEQDESK_YES=1) and provide every required setting through command-line flags, a settings JSON file, or an install profile. Do not add -y merely to hide a TTY problem when you still expect prompts.

Local PostgreSQL setup says sudo is unavailable

The installer uses sudo -n so it never blocks invisibly on a password prompt. Authenticate in the same terminal and verify the cached credential:

sudo -v
sudo -n true

Then rerun the original SeqDesk command promptly. If your account is not allowed to use sudo you still have a local option: as long as initdb and pg_ctl exist on the machine, SeqDesk creates and runs its own socket-only cluster under ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres} as your user, with no privileged command at all. Involve an administrator only when the PostgreSQL server package is missing entirely and cannot be installed, or when policy requires a shared or managed database — then pass its connection string with --database-url (and --database-direct-url if migrations use a separate endpoint). The Prerequisites page has a ready-to-send database setup request.

PostgreSQL does not start

The distro commands below apply only when SeqDesk is using a system PostgreSQL service. A cluster SeqDesk provisioned for itself is deliberately not managed by systemd, so systemctl and journalctl show nothing for it. Inspect and repair it directly:

PGROOT="${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}"
pg_ctl -D "$PGROOT/data" status
pg_ctl -D "$PGROOT/data" -l "$PGROOT/server.log" -w start
tail -n 100 "$PGROOT/server.log"

Installing a second, system-wide PostgreSQL server is not required to fix it, and no sudo is needed — the cluster’s superuser is your own login user via peer authentication.

On Ubuntu or Debian:

sudo apt-get update
sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl enable --now postgresql
pg_isready -h 127.0.0.1 -p 5432
sudo systemctl status postgresql --no-pager
sudo journalctl -u postgresql -n 100 --no-pager

On AlmaLinux, Rocky Linux, or RHEL:

sudo dnf install -y postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql
pg_isready -h 127.0.0.1 -p 5432
sudo systemctl status postgresql --no-pager
sudo journalctl -u postgresql -n 100 --no-pager

If a supported server is already listening on port 5432, investigate and reuse it instead of initializing a second server. If a distro PostgreSQL is not listening on TCP and is reachable only through /var/run/postgresql — a socket owned by the postgres system user — the installer stops instead of touching it: SeqDesk will not send generated database credentials to a server it does not own. There is no fallback in that case. Either rerun the installer as the user that owns the socket, or pass an explicit --database-url (plus --database-direct-url when migrations use a separate endpoint) for that server. Do not expose PostgreSQL port 5432, drop the database, or reinitialize its data directory as a first troubleshooting step.

The target exists or is not writable

A fresh install needs a new target whose parent is writable. Use "$HOME/seqdesk" for an evaluation, or prepare a service-owned parent as shown above for production. Do not recursively change ownership of /opt, /usr, a shared filesystem, or a PostgreSQL data directory.

Use --reconfigure only when the target is an existing SeqDesk installation. It reapplies configuration and skips the release download. Use --overwrite-existing only when you intentionally want a timestamped backup followed by replacement.

Database connection or migration fails

Start with the categorized error and protected log path printed by the installer. Rerun with --verbose (or SEQDESK_VERBOSE=1) to promote the installer’s diagnostic narration from the log file to the terminal. The log defaults to /tmp/seqdesk-install-<YYYYMMDD-HHMMSS>.log (mode 600) and can be redirected with SEQDESK_LOG; the last 20 diagnostic lines are replayed automatically on a database failure.

If SeqDesk provisioned the database itself:

PGROOT="${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}"
pg_ctl -D "$PGROOT/data" status
pg_isready -h "$PGROOT/socket"
tail -n 100 "$PGROOT/server.log"

That cluster opens no TCP port and is not a systemd unit, so pg_isready -h 127.0.0.1 and systemctl status postgresql report failure or nothing even when it is perfectly healthy. For a system PostgreSQL service you pointed SeqDesk at:

pg_isready -h 127.0.0.1 -p 5432
sudo systemctl status postgresql --no-pager
sudo journalctl -u postgresql -n 100 --no-pager

After fixing the database, rerun the command the installer prints:

npx -y seqdesk@latest -y --reconfigure --reseed-db \
  --dir "/absolute/path/to/your/seqdesk"

For a managed database, verify its host, port, credentials, firewall or outbound network policy, SSL requirement, and direct migration URL. Remove database URLs, passwords, and tokens before sharing an installer log.

SeqDesk installed, but the browser cannot connect

Check the app from the server before changing the installation:

seqdesk doctor --dir "$HOME/seqdesk" --url http://127.0.0.1:8000
pm2 status
pm2 logs seqdesk --lines 100
curl -v http://127.0.0.1:8000/api/setup/status
ss -ltn | grep ':8000'

Substitute the actual directory, URL, and PM2 command printed by the installer. A passing local request with a failing remote browser points to the bind address, firewall, reverse proxy, or DNS rather than a failed installation.

Direct script fallback

The downloaded shell script shown in Quick start is the primary guided installer; the piped form below is the non-interactive fallback. Node.js and npm are still required because the release installation uses npm internally.

Piping leaves no TTY on standard input, so the fallback requires -y; without it the installer exits with No interactive TTY detected. Use -y (or SEQDESK_YES=1) for automated installs. Enable pipefail as well, so a failed download is not hidden by the shell pipeline:

set -o pipefail
curl -fsSL https://seqdesk.org/install.sh | \
  bash -s -- -y --dir "$HOME/seqdesk"

Add sudo -v beforehand only when the PostgreSQL server package still has to be installed on this host. An unattended run on a machine that already has initdb and pg_ctl provisions SeqDesk’s own cluster under $HOME/.seqdesk/postgres without sudo.

If you need to inspect the installer or run it with prompts, download it first:

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

After a reboot

Run PM2 commands as the same Linux user that installed SeqDesk. Using sudo pm2 creates a separate root-owned process list.

pm2 status
pm2 restart seqdesk

The installer reports whether boot startup is enabled and prints the exact PM2 command it selected. If startup is not enabled, run:

pm2 startup

Run the complete privileged command printed by pm2 startup, then save the normal user’s process list:

pm2 save

If the installer selected a project-local PM2 binary, use the exact command from its completion summary instead of the global pm2 examples above.

If SeqDesk provisioned its own PostgreSQL cluster, that cluster is deliberately not a systemd service — nothing in systemctl starts it. Instead $SEQDESK_DIR/start.sh checks pg_ctl -D "${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}/data" status on every start and starts the cluster when it is down, so PM2 resurrecting the app after a reboot also brings the database back. If the app does not come up, read ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}/server.log — start.sh names it in the warning it prints when the cluster fails to start. Installs that reuse an existing PostgreSQL server contain no such step and rely on that server’s own service manager.