FAQ

Common questions about getting SeqDesk installed and running. For step-by-step guides, start with the Installation and Getting Started sections.

Requirements & Dependencies

What do I need to run SeqDesk?

Node.js 22.13.0 through 22.x or Node.js 24.x (recommended), PostgreSQL 14+, and a Linux host or local macOS application environment. The installer also uses Bash, curl, tar, npm, and a SHA-256 checksum tool. Native Windows is not supported; WSL is guidance rather than a currently tested installation target. See Prerequisites for the required-versus-extended CI matrix.

Does SeqDesk work with SQLite?

No — SeqDesk is PostgreSQL-only. SQLite is not supported for new installs. An existing SQLite instance must stay on its last SQLite-compatible release until it is manually migrated to PostgreSQL.

Do I need Conda, Nextflow, or SLURM?

Only if you run pipelines. Pipeline support is off by default. With --with-pipelines, the installer reuses a compatible Conda base or provisions Miniconda, then creates or updates the seqdesk-pipelines environment with Python 3.11, Java 17, Nextflow, nf-core, and supporting command-line tools. SLURM is optional — add it when pipeline jobs should be submitted to a cluster scheduler. The core application (sequencing orders, samples, studies, ENA submission) runs without any of them.

Installation & Quickstart

How do I install SeqDesk?

Download the installer and run it from a terminal:

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

Node.js and npm are still required by the release installation. The npm launcher remains an equivalent alternative. See the Quickstart and Linux install guides.

Where does it install, and what port does it use?

The default target is ./seqdesk relative to your current directory. For predictable installs, set an absolute path with --dir (for example bash /tmp/seqdesk-install.sh --interactive --dir "$HOME/seqdesk"). The listen port comes from your configuration (app.port or --port); installed instances default to port 8000, while the local npm run dev server uses 3000. For a production Linux target, prepare a service-owned parent first rather than assuming /opt is writable.

The installer aborts because the target directory already exists.

A fresh install refuses to overwrite an existing directory. In interactive mode it asks “Backup and replace?”; with -y it aborts instead. Pass --overwrite-existing to move the old directory to <dir>.backup.<timestamp> and replace it. See Unattended + Reconfigure.

How do I install on macOS?

Install Node.js with Homebrew, then use the guided installer:

brew install node@24
export PATH="$(brew --prefix node@24)/bin:$PATH"
 
curl -fsSLo /tmp/seqdesk-install.sh https://seqdesk.org/install.sh
SEQDESK_BIND_HOST=127.0.0.1 bash /tmp/seqdesk-install.sh --interactive \
  --dir "$HOME/seqdesk"

The guided installer resolves PostgreSQL for you: it reuses an already-running PostgreSQL 14+ server, an adoptable Unix socket, or a non-root Homebrew service. If none is available it creates a cluster it owns under $HOME/.seqdesk/postgres (override with SEQDESK_PG_HOME; the path must be 85 characters or shorter), initialized and started as your macOS login user with initdb/pg_ctl. That cluster listens on a private Unix socket only — no TCP port, no launchd service — and <dir>/start.sh starts it before the app. PostgreSQL setup must run as your normal macOS login user: never use sudo, including sudo brew services start. See Prerequisites and the dedicated macOS guide.

Database & Migrations

Migrations hang or time out (advisory-lock error on a pooled database).

migrate deploy takes a session-level Postgres advisory lock, which a transaction-mode connection pooler cannot hold — so on a pooled endpoint (such as Neon’s -pooler host) it hangs and fails with P1002. Point DIRECT_URL at the unpooled endpoint for migrations. SeqDesk also derives the unpooled URL automatically as a safety net, so a misconfigured pooled URL still works.

What is DIRECT_URL for?

DATABASE_URL is the runtime connection the app uses; DIRECT_URL is the connection Prisma uses for schema migrations. They can be the same string for a direct database. For cloud databases that put a pooler in front, set DIRECT_URL to the unpooled connection so migrations bypass the pooler. See the config file reference.

Can the installer set up PostgreSQL for me?

Yes — and in most cases you do not have to supply a database at all. Run the guided installer as a normal, non-root user: SeqDesk first reuses a healthy local PostgreSQL 14+ server (or a Unix socket) it can administer, and otherwise creates and owns a private cluster under $HOME/.seqdesk/postgres (override with SEQDESK_PG_HOME; the path must be 85 characters or shorter). That cluster is socket-only — it opens no TCP port, is not registered with launchd or systemd, and <dir>/start.sh starts it before the app on every boot.

On Linux, sudo is only needed to install the PostgreSQL server package when it is absent (sudo apt-get install postgresql / sudo dnf install postgresql-server), or to administer a pre-existing system server that SeqDesk adopts, whose role and database it creates through sudo -n -u postgres psql. Never run the installer itself with sudo: it refuses to create a PostgreSQL instance owned by root and tells you to rerun as a normal user or pass --database-url. --prepare-postgres remains available as a separate administrator bootstrap step, operating on a DATABASE_URL that already exists — the Prerequisites page includes a ready-to-send SQL template for locked-down servers where an admin must prepare the role and database first.

First Login & Security

How do I log in the first time?

Open the URL printed by the installer and use the administrator account created by the guided wizard. The packaged install defaults to port 8000. An unattended install that omits account settings creates admin@example.com / admin (facility admin) and user@example.com / user (researcher). These defaults are published and exist only for bootstrap — change or remove them immediately on any shared or network-reachable instance. If installation-time seeding could not finish, the app redirects to /setup and retries it. See First Login & Setup.

Can I expose SeqDesk to the public internet?

No. SeqDesk assumes a closed, trusted network — behind a VPN or on an institutional intranet. Convenience defaults such as open self-registration and bootstrap accounts assume that context. Note that the app binds to 0.0.0.0 (all interfaces) by default, so it is reachable from anything that can route to the host: set SEQDESK_BIND_HOST=127.0.0.1 at install time (it is persisted in <dir>/.seqdesk-bind-host and reapplied by start.sh) if the instance should only answer on the loopback interface. The public demo at demo.seqdesk.org is the only intentional exception.

Is there SSO or OAuth?

Not built in. Authentication is email + password via the NextAuth credentials provider. For single sign-on, run SeqDesk behind an identity-aware proxy (for example Cloudflare Access or Pomerium) and trust its forwarded headers.

Updates & Health

How do I update or roll back?

Use Admin → Settings → Software Updates to check for and install an application release. Upgrading the npm launcher updates the seqdesk command, not an already-installed application. Likewise, --reconfigure reapplies settings and deliberately skips the release download; it is not an update. Use the Software Updates rollback action, or re-point the active release symlink manually if the app cannot start. See Manual Update & Rollback.

How do I check that an install is healthy?

Run npx -y seqdesk@latest doctor — it is read-only and safe to run as often as you like. It verifies the install layout, that the database is reachable, and that the app answers over HTTP. Exit code 0 means no failures (warnings are allowed); exit code 1 means at least one check failed. See seqdesk doctor.