FAQ

Common questions about getting SeqDesk installed, signed in to, and kept running. Every answer here is checked against the code that produces the behaviour. For step-by-step guides, start with Installation and Getting Started.

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. Node.js 23, 25 and later majors are rejected outright rather than warned about. The installer also uses Bash, curl, tar, npm, and a SHA-256 checksum tool (sha256sum or shasum).

The install target needs free space of at least the larger of 2 GB or three times the release archive; the installer refuses to start otherwise. A SeqDesk-managed PostgreSQL cluster is created separately under $SEQDESK_PG_HOME and does not consume that budget, and neither does your sequencing data, which SeqDesk references by path rather than copying.

Native Windows is not supported — the launcher exits immediately on win32 and tells you to use WSL. 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, and the Prisma datasource names postgresql directly. The installer rejects file: URLs outright. An existing SQLite instance must stay on its last SQLite-compatible release until it is manually migrated to PostgreSQL.

Can I run it on Windows?

Not natively. Run it under WSL, or on a Linux VM or server. The seqdesk launcher stops on process.platform === "win32" before doing anything.

Do I need Conda, Nextflow, or SLURM?

Only if you run pipelines, and pipeline support is off by default. The core application — sequencing orders, samples, sequencing runs, studies, file discovery and assignment, support tickets, and ENA submission — runs without Conda, Nextflow, Java, or a scheduler installed anywhere.

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 on top of that — add it when pipeline jobs should be submitted to a cluster scheduler rather than run on the SeqDesk host itself.

Leaving pipelines off is the right default for a facility that only needs order and sample management, or that runs its analyses elsewhere. See Pipelines & Analysis.

Can I add pipelines to an install that does not have them?

Yes. Re-run the installer against the same directory with --with-pipelines, adding --reconfigure so it keeps the installed release instead of downloading one:

npx -y seqdesk@latest -y --reconfigure --with-pipelines --dir "$HOME/seqdesk"

In reconfigure mode the installer loads the existing installation’s values first, so an install that already had pipelines keeps them without repeating the flag; an explicit --with-pipelines or --without-pipelines on the command line always wins over the remembered value.

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"

Downloading to a file rather than piping matters: piping occupies standard input, so there is no TTY for the wizard’s prompts and the installer refuses interactive mode with No interactive TTY detected. Node.js and npm are still required by the release installation. The npm launcher (npm i -g seqdesk@latest, then seqdesk --interactive) remains an equivalent alternative. See the Quickstart and Linux install guides.

Do I need root or sudo?

No, and you should not use it. Run the installer as your normal user account.

• The installer refuses to create a PostgreSQL cluster owned by root — the server would never start — and tells you to rerun as a normal user or pass --database-url for a database you already manage.
• On macOS, PostgreSQL setup never uses sudo at all. sudo brew services start is specifically the wrong thing to do.
• On Linux, sudo is needed only in two narrow cases: installing the PostgreSQL server package when it is absent (sudo apt-get install postgresql / sudo dnf install postgresql-server), or administering a pre-existing system PostgreSQL, whose role and database the installer creates through sudo -n -u postgres psql. Because those use sudo -n, they need a cached credential — run sudo -v beforehand if they apply.
• If npm i -g fails with EACCES, that is an npm prefix permission problem, not a reason to install SeqDesk as root. Use npx -y seqdesk@latest … or a Node.js version manager instead; see npm launcher permissions.

The application itself should run as a non-root service account.

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 a development npm run dev server uses 3000. For a production Linux target, prepare a service-owned parent first rather than assuming /opt is writable.

Inside the install directory, settings.json holds the runtime configuration (written chmod 600), start.sh launches the app, and current/ is a symlink to the release that is actually running. Updates and rollbacks re-point that symlink; your configuration lives at the root and is not part of a release.

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.

Read what that does not cover before answering yes: it moves the install directory and nothing else. The PostgreSQL database is a separate object with a separate lifetime — it is not backed up, not dropped, not reset, and its user accounts keep their passwords. To start from an empty database, install against a different one with --database-url. See Unattended + Reconfigure.

What happens if I install a second time against the same database?

The database is reused: the schema is migrated forward and every account, sequencing order and record in it is kept. Crucially, the seed never overwrites an account that already exists — if it did, anyone who could run the installer against a connection string could reset that database’s administrator password.

So the installer reports The selected database already contains SeqDesk accounts, names them, and prints existing password (unchanged) in the closing Login block instead of a password. Any password it would otherwise have shown you does not open that installation. Sign in with the credentials the database was originally set up with; if they are lost, see Reset a password. The full walkthrough, including the two narrower variants of the message, is in the install attached to a database that already had accounts.

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"

You do not install or start PostgreSQL yourself. The guided installer resolves it 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; macOS caps Unix socket paths, so the cluster’s socket/ subdirectory must be at most 85 characters — keep SEQDESK_PG_HOME to 78 or fewer), 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

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 cluster’s socket/ subdirectory must be at most 85 characters, so keep the path short). 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.

A local socket owned by a different operating-system user (typically a distribution PostgreSQL on /var/run/postgresql owned by postgres) is skipped with a warning rather than used: SeqDesk declines to send generated credentials to a server it does not own. No action is needed — it continues down the ladder and normally creates its own cluster.

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

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.

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. For Neon-style hosts SeqDesk also strips the -pooler label automatically as a safety net, so a misconfigured pooled URL still works; other poolers (for example a standalone PgBouncer on its own hostname) have no such fallback and must be pointed at the direct endpoint yourself.

Where does my sequencing data actually live?

Not in the database and not in the install directory. SeqDesk records the path of each FASTQ file and reads it in place; the files stay wherever your sequencer or storage puts them, under the base path configured at Settings → Infrastructure → Open Data Storage (site.dataBasePath, also settable at install time as sequencingDataDir). That is why moving or unmounting that storage breaks file access even though the database is untouched, and why the database backup you take is small. See Sequencing Files and Data Storage.

Accounts, First Login & Security

How do I log in the first time?

Open the Browser URL from the installer’s closing summary and use the administrator account from the Login block printed just above the success banner. The packaged install defaults to port 8000, so that URL is normally http://127.0.0.1:8000. If you left the wizard’s password prompt blank, the installer generated a password and prints it there once — it is kept out of the install log, so copy it before closing the terminal.

An unattended install that configures nothing at all, against a genuinely empty database, 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. The seed deliberately refuses to create an account with that built-in password in the two cases where it would be dangerous: when the install named an account but no password for it, and when the database was already configured by something before. In those cases the account is simply not created, which is visible at the login screen and explained in the application log.

If installation-time seeding could not finish, the app redirects to /setup and retries it. See First Login & Setup.

I forgot the administrator password. What now?

Use seqdesk reset-password from a shell on the host:

npx -y seqdesk@latest reset-password admin@example.com --dir "$HOME/seqdesk"

It resets exactly one account, shows you what it is about to change and asks for confirmation, and prints the new password once — it is stored nowhere else, because SeqDesk keeps only the bcrypt hash. It reads the database connection from the install directory’s settings.json, so you do not need the connection string yourself. It requires SeqDesk 1.1.125 or newer installed in that directory. Full reference, including the JSON mode and every error it can produce: Reset a password.

Can users reset their own passwords?

No. There is no “forgot password” email flow, no reset link on the login page, and no change-password screen for a signed-in user. seqdesk reset-password is currently the only way to change the password of an existing account; the only route in the application that hashes a password is POST /api/register, which creates a new account.

Plan around that: give the administrator account an address a real person still controls, and store its password where your facility already stores credentials. Note also that sessions are JWTs, so resetting a password does not sign out a browser that is already logged in as that account.

Who can create an account?

Two different paths, with two different guards:

• Researchers self-register at /register. The request must supply an email, password, first and last name, and the role RESEARCHER. If the optional account validation module is enabled, an email domain outside the configured allow-list is either rejected (Registration is restricted to email addresses from: …) or merely warned about, depending on enforceValidation.
• Facility admins cannot self-register. role: "FACILITY_ADMIN" requires a valid invite code that has not been used and has not expired; if the invite was issued for a specific address, the registering email must match it. Invites are created by an existing admin.

SeqDesk has exactly these two roles. There is no finer-grained permission model: a facility admin sees and can change everything, a researcher sees their own sequencing orders (plus their department’s, when access.departmentSharing is on). See User Management.

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 researcher 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, with JWT sessions. 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 the sidebar’s Settings → Info page (titled “Platform Info”, at /admin/settings) and its Software Updates section 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 --dir "$HOME/seqdesk" --url http://127.0.0.1:8000 — it is read-only and safe to run as often as you like. Without --dir it checks the current working directory. It verifies the install layout, that the configuration parses and carries the required secrets, that the database host accepts a TCP connection, 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 (and 2 means the options themselves were invalid).

What does the health check not cover?

More than people expect, so do not read a clean report as “ready for production”. Doctor never authenticates to the database (the PostgreSQL check is a bare TCP connect, not a query), never inspects the schema, and never proves that a usable account exists. It checks nothing at all about your sequencing data path, the Conda/Nextflow/SLURM toolchain, ENA credentials, TLS, the bind address, or backups. It is also strictly read-only: it never repairs anything it finds. The complete list is on the doctor page.

On a default install the database also listens on a Unix socket, and this release’s health check only probes TCP — so it reports the PostgreSQL check as unreachable and exits 1 even when the database is fine. Confirm the database separately with pg_isready -h ~/.seqdesk/postgres/socket and read the known limitation before treating that failure as real. For the same reason, do not gate CI on doctor’s exit code for socket-based installs.

Where are the logs?

Three different places, for three different failures:

• The install itself — /tmp/seqdesk-install-<timestamp>.log (or wherever you pointed SEQDESK_LOG). Re-run with --verbose to promote the diagnostic narration to the terminal as well. Strip database URLs, passwords and tokens before sharing one.
• The running application — pm2 logs seqdesk --lines 100 under PM2, or the file you redirected start.sh into for a manual start (the installer suggests nohup <dir>/start.sh > <dir>/seqdesk.out 2>&1 &). A manual start does not come back after a reboot.
• A SeqDesk-managed database — server.log inside ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}.

Pipeline runs keep their own logs/pipeline.out and logs/pipeline.err inside the run directory; see Monitoring.