Quickstart
This is the shortest path from “nothing installed” to “a sequencing order that has been submitted, had files attached, and been published back to the researcher”. It is written for one person on one machine, wearing both hats.
It is worth doing even if you already know you want SeqDesk: it exercises every part of the chain — database, seeding, forms, the file scanner, the delivery gate — so that when a real order arrives you know which pieces are already proven.
Budget about twenty minutes, most of it waiting for the installer.
1. Install
Downloading the installer first is the recommended path: the script keeps its
guided prompts attached to your terminal and needs no global npm package.
npm i -g seqdesk@latest && seqdesk --interactive is an equivalent alternative
if you prefer a global command — the launcher downloads and runs the same public
installer.
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, and bind to
loopback only for a local evaluation:
SEQDESK_BIND_HOST=127.0.0.1 bash /tmp/seqdesk-install.sh --interactive \
--dir "$HOME/seqdesk"Without SEQDESK_BIND_HOST, SeqDesk listens on 0.0.0.0 — every interface on
the host. For an evaluation on a shared machine, bind to loopback.
On Linux, a home-directory target avoids running the app installer as root — and
you should not use sudo, because SeqDesk will not create a database owned by
root. You do not need to prepare PostgreSQL: the installer reuses a healthy
local server, or creates its own under ~/.seqdesk/postgres. See the
Linux install guide for Ubuntu/Debian,
RHEL-family, and production-directory instructions.
On a Mac, install the prerequisites with Homebrew first, then run the same installer — see the macOS install guide.
Add --with-pipelines if you want to try a Nextflow workflow in this run.
It provisions Conda and the seqdesk-pipelines environment, which adds
several minutes. Everything else on this page works without it.
2. Sign in
Open SeqDesk
Open the Browser URL printed in the installer’s closing summary. For the
local command above that is http://127.0.0.1:8000. (The summary also prints a
Local health URL — use that one for curl and seqdesk doctor, not for the
browser.) The installer has already checked PostgreSQL, applied the schema, and
seeded the configured bootstrap accounts.
Sign in as administrator
The last thing the installer prints before the success banner is a Login block with the accounts it created. Use the administrator email and password you created in the guided installer. If you left the password prompt blank, the installer generated a strong one and shows it here — once, and never in the install log — next to the note “Save the generated passwords now”. A password you typed yourself is never echoed back.
If you used unattended mode (-y) on a fresh database without configuring
accounts, the published bootstrap defaults are admin@example.com / admin and
user@example.com / user. Change or remove them immediately before allowing
another machine to reach the service. For the exact rules on when SeqDesk does
and does not create those accounts, see
First Login & Setup.
3. Do the minimum configuration
You only need three things for this walkthrough. The full list is in the Admin Quickstart.
Create a department
Users → Departments (/admin/departments). Add one — the researcher account
you make next has to pick something from this list.
Add a sequencer
Settings → Sequencers (/admin/sequencing-tech). Add one platform and one
instrument. Without this, the Sequencing Technology field on the order form
has nothing to offer.
Set the data storage path
From the SeqDesk host, create and verify the deliberately new directory used by this walkthrough:
seqdesk storage configure "$HOME/seqdesk-data" --create
seqdesk storage statusFor production, substitute an existing absolute facility directory and omit
--create. Nothing can be attached to a sample until storage is ready, and the
sidebar’s Infrastructure entry carries a warning badge until it is. The
equivalent UI is Settings → Infrastructure → Data Storage
(/admin/data-storage).
Create a run folder inside the configured directory now, and drop in a pair of FASTQ files named so the scanner can pair them:
mkdir -p "$HOME/seqdesk-data/RUN-2026-01"
cd "$HOME/seqdesk-data/RUN-2026-01"
# any small gzipped FASTQ pair will do
touch sampleA_R1.fastq.gz sampleA_R2.fastq.gzThe scanner walks two directory levels below the base path by default and only
matches .fastq.gz, .fq.gz, .fastq and .fq.
The facility name and contact email come from the config file
(site.name, site.contactEmail in settings.json) rather than an admin form —
see the Config File Reference.
4. Raise a sequencing order as a researcher
Get a researcher account
Sign out and go to /register to create a researcher account, or sign in with
the optional researcher account the guided installer offered to create. Use a
different browser profile or a private window if you want both roles open at
once.
Run the order wizard
From the Sequencing Orders page, start a new order. With the shipped default form the wizard has four steps:
- Sequencing Order Details — Sequencing Order Name (required) and Number of
Samples. Set the sample count to
1for this walkthrough. - Sequencing Information — Sequencing Technology, Library Strategy, Library Source.
- Samples — one row. Fill in Organism (use the taxonomy autocomplete) and Sample Title.
- Review — check it, then finish.
There is no save-as-draft. Finishing the wizard creates the order, writes the samples and submits it in one action — after which the sample table is frozen.
Confirm what happened
The order now appears on the Sequencing Orders page with status SUBMITTED
and a number like ORD-20260415-0001. The order detail page shows a three-step
Sequencing Order Process panel; press Mark sent on step 2 to simulate
shipping the physical samples.
5. Process it as the facility
Attach the files
Sign back in as the admin, open the order, and go to Sequencing Data →
Associate. SeqDesk lists the FASTQ files it found under the data base path and
pairs _R1 with _R2. Link the pair to your sample.
As soon as the only sample has a file, SeqDesk flips the order to COMPLETED by itself and writes the note “Automatically completed - all samples have sequencing files”.
Publish the delivery
Still on Sequencing Data, find the Delivery to user card and press
Make downloadable to user. This is the step people forget: until you press
it, the researcher cannot see or download anything, and the API answers
Sequencing files are not available for this sequencing order.
If the button will not enable, your reads are probably not classified as cleaned — only cleaned, active reads are deliverable.
Check it from the researcher’s side
Sign back in as the researcher. The order reads COMPLETED and the sequencing
files are now downloadable. That is the loop closed.
What you have just proved
- PostgreSQL is reachable and the schema and seed applied cleanly.
- Authentication, registration and both roles work.
- The order form renders and submits, and the status ladder behaves.
- The file scanner can see your storage and pair reads correctly.
- The delivery gate publishes to the right person.
Anything that failed above is worth fixing before real data arrives. Common problems is a symptom-to-fix table, and the FAQ covers the questions people ask during a first install.