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 18 or newer (Node.js 20 LTS is recommended for long-running installs), a PostgreSQL database, and a supported OS — AlmaLinux, Rocky Linux, RHEL, Debian, Ubuntu, or a local macOS install. The npm launcher and installer also use Bash, curl, and tar. See Prerequisites for the full list, including CPU architecture and writable-directory notes.

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. Conda (or Miniconda) builds the pipeline runtime environments, Nextflow runs the packaged workflows, and SLURM is optional — add it when pipeline jobs should be submitted to a cluster scheduler. The core application (orders, samples, studies, ENA submission) runs without any of them.

Installation & Quickstart

How do I install SeqDesk?

The supported entry point is the npm launcher:

npm i -g seqdesk && seqdesk

The launcher downloads and runs the public installer internally, so you normally do not call install.sh yourself. When npm is unavailable, the advanced fallback is curl -fsSL https://seqdesk.com/install.sh | bash. See the Quickstart.

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 seqdesk -y --dir /opt/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.

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 the prerequisites with Homebrew, then use the npm launcher the same way as on any platform:

brew install node postgresql@16 && brew services start postgresql@16
npm i -g seqdesk && seqdesk

PostgreSQL must be running before you install. Pass --dir ~/seqdesk to set an explicit install location. See Prerequisites and the Quickstart.

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, with sudo. Run the installer with --prepare-postgres and SEQDESK_DATABASE_URL to create a fresh role and database, then exit. Without sudo, an admin must prepare the role and database first — the Prerequisites page includes a ready-to-send SQL template for locked-down servers.

First Login & Security

How do I log in the first time?

Browse to your instance’s URL. When the database has not been configured yet, the setup wizard runs automatically, checks the PostgreSQL connection, and applies the schema. Seeded bootstrap accounts are 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. 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. The public demo at demo.seqdesk.com 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?

Upgrade the launcher (npm i -g seqdesk@latest) and run it again, or re-run the installer with --reconfigure against your infrastructure JSON. --reconfigure preserves data by default (it skips DB push and seed). If an update fails before it activates, the installer automatically restores the timestamped backup. See Manual Update & Rollback.

How do I check that an install is healthy?

Run seqdesk 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.