Skip to Content
InstallationQuickstart

Quickstart

Download the installer to a file and run it from a terminal for guided setup. Node.js and npm must already be available. Before installing on a shared server, review the installation prerequisites. You normally do not need to prepare a PostgreSQL role or database yourself: the installer reuses a local server you already own, or creates and owns its own cluster. Supply --database-url only for a database you already run, such as a managed or remote server.

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

This downloads the current public installer over HTTPS before executing it, so the guided prompts retain access to your terminal and you can inspect the file first if required. The release installation still uses Node.js and npm. Fresh installs provision the core application only; add --with-pipelines when this host should also install Conda, Java, and Nextflow.

The optional npm launcher runs the same public installer and pins SEQDESK_VERSION to the npm package version (unless you set it yourself), so an older launcher installs the matching older application release. Its tarball also ships a manual install checklist  useful for end-to-end verification on a fresh host.

Installer output and behavior come from the deployed SeqDesk.com/public/install.sh file. Changes made in the SeqDesk app repository are not visible to the downloaded installer or npm launcher until that public installer file has been updated and SeqDesk.com has been deployed.

Install location depends on where you run the command. The default target is ./seqdesk relative to your current directory.

For predictable installs, set an explicit absolute path with --dir:

bash /tmp/seqdesk-install.sh --interactive --dir "$HOME/seqdesk"

The directory must be new for a fresh install. Use --reconfigure for an existing SeqDesk installation. --overwrite-existing creates a timestamped backup and replaces the directory; use it only when replacement is intentional.

For Linux, use a home-directory target for an evaluation or prepare a service-owned parent before installing on a shared server. Local PostgreSQL provisioning does not need sudo: the installer creates a cluster under $HOME/.seqdesk/postgres owned by your login user. A current sudo credential is only needed when the PostgreSQL server package is missing and has to be installed, or when an existing system PostgreSQL must be administered. Do not run the installer itself with sudo; it refuses to create a PostgreSQL instance owned by root. See the Linux install guide.

For local macOS installs, install Homebrew Node.js first and use the same downloaded installer. It provisions or reuses local PostgreSQL and diagnoses Homebrew service conflicts; see the macOS install guide.

npm launcher alternative

If you prefer a globally installed command-line launcher, this remains equivalent:

npm i -g seqdesk@latest
seqdesk --interactive --dir "$HOME/seqdesk"

Upgrade the launcher before using it to install a newer application release.

For a fully specified non-interactive install, the script can also be piped to Bash:

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

The piped form is intended for fully specified, non-interactive installs because standard input is occupied by the download. Node.js and npm must already be available whichever entry point you choose. The default local PostgreSQL setup needs no sudo, because SeqDesk provisions its own cluster as your login user. Run sudo -v beforehand only on Linux when the PostgreSQL server package still has to be installed, or when an existing system PostgreSQL must be administered through sudo -n -u postgres.

What this gives you

  • Core SeqDesk platform on your own infrastructure
  • Interactive prompts for database and bootstrap-account settings
  • A baseline setup you can later convert into unattended automation

Guided wizard (--interactive)

For a first install, add --interactive for a short setup wizard that walks you through the choices most people get wrong on the first try:

bash /tmp/seqdesk-install.sh --interactive --dir "$HOME/seqdesk"

It asks:

  • Database — use a local PostgreSQL the installer sets up, or paste an existing/managed connection string. For a managed URL it runs a quick reachability check and tells you whether the host looks reachable before the install continues (full credentials are verified later, during migrations).
  • Accounts — the admin email/password and an optional researcher (non-admin) account. Emails are validated, passwords must be at least 8 characters and are confirmed, and you can leave a password blank to have a strong one generated and shown once.

The wizard only changes what you’re prompted for — it does not run under -y, --config, or --profile, so automated and unattended installs are unaffected.

For a local-only evaluation, set SEQDESK_BIND_HOST=127.0.0.1. The default server bind listens on all interfaces and is intended only for a protected VPN or institutional network. Never expose bootstrap credentials directly to the public internet.

PostgreSQL setup

SeqDesk needs a PostgreSQL database before migrations can complete, but in most cases you do not have to supply one. The installer works down a ladder: it reuses a healthy server already answering on the configured connection; failing that, a local Unix socket it can administer; on macOS it starts an already-registered but idle Homebrew service; and if none of that applies it creates its own private cluster under ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres} and generates the credentials itself. PostgreSQL 14 or newer is required when an existing socket is adopted, and SQLite is rejected.

On Linux, the private cluster needs no sudo: it is owned by your login user and peer-authenticated. Privileged operations use sudo -n and therefore need a current cached credential, but they are only reached when the PostgreSQL server package is absent and must be installed, or when a pre-existing system PostgreSQL has to be administered. Never run the installer itself under sudo; it refuses to create a PostgreSQL instance owned by root.

Provide your own connection string with --database-url (or SEQDESK_DATABASE_URL) when you have a managed or remote database, or when a locked-down server requires the administrator to prepare the database first. An explicit URL is never silently retargeted: if it is unreachable, the installer reports the failure and stops on macOS, and defers to the existing system setup on Linux.

On macOS, the installer adopts an already-registered Homebrew PostgreSQL service only when that service runs as your login user; it never uses sudo for PostgreSQL. When no usable server exists it creates its own cluster instead, so you do not have to install or start PostgreSQL yourself. See the macOS install guide for verification steps.

When the selected database already contains SeqDesk tables, the installer warns and reports existing user/order counts before migrations. Migrations preserve and update that database; choose a different --database-url when you want an isolated instance.

The database SeqDesk creates for you

The private cluster is socket-only. It opens no TCP port, so psql -h 127.0.0.1 never reaches it; the generated connection URL points at the socket directory under ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres} instead, and your own OS user is its superuser through peer authentication.

The cluster is deliberately not registered with launchd or systemd. The install directory’s start.sh checks it and starts it before launching the app, so the database comes back with SeqDesk after a reboot. Set SEQDESK_PG_HOME to relocate the cluster, and keep that path short: the macOS Unix-socket limit caps it at 85 characters.

Verify the install

After the installer finishes, run seqdesk doctor through npx against the install directory to confirm the layout is intact, the database is reachable, and (if the app is running) the HTTP probes pass:

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

Release installs keep immutable application files under the install root’s current directory. Pass the install root ($HOME/seqdesk in this example) to doctor; it resolves the active release automatically.

Release download and dependency installation can take several minutes. Conda setup runs only with an explicit pipeline opt-in. The installer keeps updating its status and prints the protected log path. On failure, use the final error and log path rather than rerunning with --overwrite-existing blindly.

Troubleshooting

Start with the final error line and the protected log path printed near the top and bottom of the installer output. Diagnostic narration is written only to the log by default; add --verbose to promote that detail to the terminal while the install runs. Remove database URLs, passwords, access codes, and tokens before sharing a log.

npm cannot install the launcher globally

An EACCES error from npm i -g seqdesk@latest means the active npm prefix is not writable by your user. Do not run the whole SeqDesk installation as root. Use a Node.js version manager, as recommended in npm’s permissions guide , or run the launcher without a global install:

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

Choose a new target directory. On a centrally managed server, an administrator can instead install the launcher into the system npm prefix.

The installer stops before downloading SeqDesk

Preflight failures do not download a release, move an existing directory, or create the install target. Check the values the installer actually sees:

command -v node npm curl tar
node --version
npm --version
df -h .

Node.js must be 22.13.0 or newer on the 22.x line, or any supported 24.x release. Node.js 23, 25, and newer majors are not accepted yet. Install any missing curl, tar, and sha256sum/shasum tool using the exact platform-specific command printed by the installer, then rerun the same SeqDesk command.

To inspect the most recent protected log:

ls -1t /tmp/seqdesk-install-*.log | head -n 1
tail -n 120 /tmp/seqdesk-install-YYYYMMDD-HHMMSS.log

Replace the example filename with the path printed by the first command.

The target exists, is not writable, or has too little space

A fresh install requires a new directory. Choose a different --dir, or use --reconfigure only when the target is an existing SeqDesk installation and you intend to reapply its configuration. Reconfigure mode deliberately skips the release download; it is not an application update.

--overwrite-existing moves the current directory to a timestamped backup and installs a replacement. Do not use it as a generic retry switch. For permission or disk errors, choose a writable filesystem or have an administrator fix the specific target parent; do not recursively change ownership of /opt, /usr, or a PostgreSQL data directory.

PostgreSQL cannot be reached or migrations fail

When SeqDesk provisioned its own cluster, that cluster is socket-only and is not a systemd service, so pg_isready -h 127.0.0.1 and systemctl report nothing about it. Check it directly:

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

For a pre-existing system database on Linux, check the service and its recent log instead:

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

For a managed database, verify the hostname, port, credentials, firewall or outbound-network policy, SSL requirement, and DIRECT_URL. A pooled Neon DATABASE_URL should be paired with the direct connection string for migrations. The installer distinguishes refused connections, DNS failures, timeouts, invalid passwords, missing roles/databases, pg_hba.conf rejection, and missing SSL in its final error.

Do not expose PostgreSQL port 5432 publicly, drop the database, or reinitialize its data directory as a first troubleshooting step. Fix the reported cause and rerun the same command.

Installation finishes, but the app does not answer

Run the read-only health check against the installation root:

npx -y seqdesk@latest 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

If you selected another directory or port, substitute those values. A passing local curl with a failing remote browser points to a firewall, reverse proxy, bind address, or routing problem rather than a failed SeqDesk install.

The direct shell fallback needs explicit input

The piped command is documented as a non-interactive fallback. Download the script to a file for the guided wizard, or pass -y plus every required value. In automation, enable Bash pipefail so a failed curl cannot be hidden by the pipeline:

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

From source

For development checkouts or CI, use the source installer instead of the distribution one:

bash scripts/install.sh -y --dir ./seqdesk-source

The source installer accepts most of the same runtime, secret, and pipeline flags as the distribution installer, plus --branch <branch> to pin the Git ref (it has no --version). It does not support the distribution-only flags:

  • --reconfigure / --reseed-db
  • --prepare-postgres
  • --use-pm2 / --no-pm2
  • --run-doctor
  • --additional-setting / --additional-settings / --additional-settings-file
  • --pipeline-db-dir / --pipeline-database-dir

Override the upstream repository with SEQDESK_REPO, the branch with SEQDESK_BRANCH.