SeqDesk

Status	What it verifies
	Unit & integration test suite, run on every push
	Source-code coverage of src/**, reported to Codecov
	Browser (UI) end-to-end tests against a live instance (see PLAYWRIGHT_TESTS.md)
	Order-level pipelines (simulate-reads, FASTQ checksum, FastQC) run end to end on small synthetic reads, plus read-cleaning promotion writeback
	Study-level pipelines (simulate-reads, study demo report, nf-core/mag) run end to end on small synthetic reads; nf-core/mag runs a reduced configuration (megahit assembly only — bin QC, GTDB-Tk taxonomy, and annotation are skipped), verifying the wiring rather than producing a real assembly
	Install (tarball, npm, source, PM2) → boot → admin & researcher login, on Ubuntu
private CI	SLURM pipeline execution as a real Slurm job (sbatch/squeue/sacct), on small synthetic reads
private CI	AlmaLinux install, then boot
release gate	In-app update to a new release + one-click rollback, applied on a real PM2 install and verified to preserve data (run before each release)

The SLURM and AlmaLinux rows run on a private self-hosted mirror (a real SLURM cluster and a production-like AlmaLinux box); the update/rollback release gate runs before each release through the in-app updater. These are exercised on demand rather than on every push, so they are not badged here.

Sequencing facility management — from order submission to data publishing. SeqDesk handles sequencing orders, samples, studies, sequencing files, and bioinformatics pipeline execution, and runs self-hosted on your own infrastructure.

📖 Full documentation: seqdesk.com/docs — installation, configuration, orders & studies, sequencing files, pipelines, ENA submission, administration, and updates. This README covers installing and developing the repository itself.

Features

• Orders & samples — submit and track sequencing orders; collect per-sample data with configurable forms.
• Studies & metadata — group samples across orders into studies with standardized MIxS metadata.
• Sequencing files — discover, assign, and track raw/cleaned read files with checksums and barcode-based matching.
• Pipelines — run bioinformatics workflows (FASTQ QC, read cleaning, assembly/MAG, …) locally or on SLURM, with live monitoring and result write-back.
• ENA submission — register studies and samples and submit reads, assemblies, and bins to ENA.
• Self-hosted — runs on your own infrastructure; your data stays with you.

Deployment Environment

SeqDesk is designed to run inside a closed, trusted network, for example behind a VPN or restricted to an internal/institutional intranet. It should not be exposed directly to the public internet. Access should be limited to authorized users on the protected network. Convenience-oriented defaults, including open self-registration and bootstrap accounts, assume this trusted-network context; deploying SeqDesk on a publicly reachable host is not a supported or secure configuration.

The public demo at demo.seqdesk.com is the intentional exception. It is a sandbox for exploring the UI. Open https://demo.seqdesk.com/demo for the researcher view or https://demo.seqdesk.com/demo/admin for the facility-admin view; each visitor gets their own disposable, isolated demo workspace (tracked by a browser cookie and cleaned up automatically after a few hours of inactivity). You can optionally append ?workspace=<key> to open or resume a specific named workspace — handy for sharing a populated sandbox or returning to one later — but anyone using the same key shares that workspace and its data, so leave it off to get a fresh private one. These entry points bootstrap a temporary demo session; the plain /admin route is the normal protected dashboard, not a demo entry point. This does not change the deployment guidance for real SeqDesk instances.

Requirements

• Node.js 18+
• PostgreSQL (SeqDesk is PostgreSQL-only)
• Optional, for pipelines: Conda and/or Nextflow — and SLURM for cluster execution

Install

Recommended — the npm launcher handles installs and upgrades:

npm i -g seqdesk
seqdesk

Installer flags pass straight through the launcher, for example:

seqdesk -y --config ./infrastructure-setup.json

Fallback when npm is unavailable:

curl -fsSL https://seqdesk.com/install.sh | bash

Full installation, configuration, and unattended options are documented at seqdesk.com/docs/installation.

The npm package is the supported public entry point; it downloads and runs the public installer served from seqdesk.com/install.sh. Editing scripts/install-dist.sh in this repository does not change the live installer until the matching public/install.sh in the SeqDesk.com repository has been updated and deployed.

Ways to install SeqDesk

Every path boots the same app — pick by your scenario. The methods below are exercised end to end by continuous integration (install → boot → reachable over HTTP → database migrated; see the badges above for live status):

Method	Command	Best for	Verified in CI
npm launcher (recommended)	npm i -g seqdesk then seqdesk	Almost everyone — supported install + upgrade path	Ubuntu · AlmaLinux · macOS
One-line installer	curl -fsSL https://seqdesk.com/install.sh | bash	Fallback when npm is unavailable	Ubuntu
macOS (Homebrew)	npm i -g seqdesk && seqdesk	Local Mac workstation / dev installs	macOS
Unattended	seqdesk -y --config ./infrastructure-setup.json	Fleet or scripted deployments; update in place with --reconfigure	Ubuntu
From source	bash scripts/install.sh	Developers / CI building a specific branch	Ubuntu · AlmaLinux

The npm-launcher and source installs are also exercised under PM2, and the npm/AlmaLinux/macOS runs verify an administrator can log in to the running app.

FAQ

A few common installation and setup questions. See the full FAQ for more.

What do I need to run SeqDesk? Node.js 18+ (20 LTS recommended), a PostgreSQL database, and Linux or macOS. Pipelines are optional and add Conda/Nextflow (plus SLURM for cluster execution).

Does it work with SQLite? No — SeqDesk is PostgreSQL-only. An existing SQLite instance must stay on its last SQLite-compatible release until it is migrated to PostgreSQL.

How do I log in the first time? Browse to the instance URL — the setup wizard checks the database and applies the schema automatically. Seeded bootstrap accounts are admin@example.com / admin and user@example.com / user; change or remove them immediately on any shared instance.

The installer aborts because the directory already exists. With -y it refuses to overwrite. Pass --overwrite-existing to back the old directory up to <dir>.backup.<timestamp> and replace it.

Migrations hang or time out on a pooled database (e.g. Neon). Point DIRECT_URL at the unpooled endpoint — migrate deploy needs a session-level advisory lock a transaction pooler can't hold. SeqDesk also derives the unpooled URL automatically as a safety net.

Can I expose SeqDesk to the public internet? No — it assumes a trusted, closed network (VPN or intranet). The public demo at demo.seqdesk.com is the only intentional exception.

How do I check an install is healthy, or update and roll back? seqdesk doctor (read-only) verifies layout, database reachability, and HTTP. Updates go through the npm launcher; a failed update automatically restores the timestamped backup.

Local development

git clone https://github.com/hzi-bifo/SeqDesk.git
cd SeqDesk
npm ci
cp seqdesk.config.example.json seqdesk.config.json   # set runtime.databaseUrl and nextAuthSecret
npm run db:migrate:deploy
npm run db:seed
npm run dev                                           # http://localhost:3000

On macOS with Homebrew PostgreSQL, npm run dev:mac starts/creates the local database, runs migrations and seed data, and launches the dev server in one step.

Default seeded users are intended for local development/bootstrap only:

• Admin — admin@example.com / admin
• Researcher — user@example.com / user

For any shared or network-reachable instance, prefer configuring real bootstrap accounts before the first seed/install. If you use the defaults, change or remove those accounts immediately after first login. Later config edits do not rotate passwords for accounts that already exist.

Generate one bcrypt password hash per account after npm ci:

node -e 'const { hashSync } = require("bcryptjs"); console.log(hashSync(process.argv[1], 12));' 'replace-with-strong-password'

Then add the accounts to seqdesk.config.json before running npm run db:seed:

{
  "bootstrap": {
    "users": {
      "admin": {
        "email": "seqdesk-admin@your-org.example",
        "passwordHash": "$2b$12$...",
        "firstName": "SeqDesk",
        "lastName": "Admin",
        "facilityName": "Your Facility"
      },
      "researcher": {
        "email": "first-user@your-org.example",
        "passwordHash": "$2b$12$...",
        "firstName": "First",
        "lastName": "User",
        "institution": "Your Institution",
        "researcherRole": "POSTDOC"
      }
    }
  }
}

For configuration details, testing, the live test dashboard, background workers, and the pipeline e2e harnesses, see CONTRIBUTING.md.

Documentation

• User & operator guide: seqdesk.com/docs
• Releases and update info: seqdesk.com

License

Licensed under the Apache License 2.0 — see LICENSE.