Admin Quickstart

Replace the bootstrap credentials

Sign in with the account the installer created. If this was an unattended install on a brand-new database that named no accounts, SeqDesk seeded the published defaults admin@example.com / admin and user@example.com / user. Change or remove them before the host is reachable from anywhere else.

To reset a password from the shell:

cd "$HOME/seqdesk"
seqdesk reset-password admin@example.com

There is no self-service password reset in the application, so this is also how you recover a locked-out researcher later.

Set the facility identity

Facility identity is config-file driven, not an admin form. Set site.name and site.contactEmail in the install directory’s settings.json (see the Config File Reference) and restart the app — or import a JSON setup file from Settings → Infrastructure → Import settings.json.

The branding columns on the SiteSettings row (primaryColor, secondaryColor, logoUrl, faviconUrl, helpText) are seeded with defaults and have no admin form; they are not part of the supported configuration surface.

Create departments

Go to Users → Departments (/admin/departments) and add your research departments.

Do this before anyone registers. The registration form fetches this list and offers it as Select department…; if the list is empty, researchers register without one and you will be reassigning them by hand. Departments also drive the Department Sharing toggle under Settings → Accounts → Access & Sharing, which widens a researcher’s order list from “mine” to “my department’s”. That toggle applies to sequencing orders only — studies stay strictly per-owner.

Decide which modules are on

Settings → Modules (/admin/modules) lists nine modules, eight of which have a working switch. Do this before customising the forms, because modules add and remove whole field groups.

Sequencing Technology’s switch is permanently disabled — the module is always enabled. The module list itself is compiled into the build: you can toggle the other eight, but adding a tenth needs code.

Several module cards also carry Form actions that write straight into the order form — Add Sequencing Tech to Sequencing Order Form, Add Barcode to Sequencing Order Form, Apply ONT Run Plan Preset, Add ENA Fields to Sequencing Order Form, Add MIxS to Study Form. Enabling a module does not place its fields for you; these buttons do. Add Barcode stays disabled until the sequencing-tech field exists, so use them top to bottom.

Configure sequencers

Under Settings → Sequencers (/admin/sequencing-tech, titled “Sequencing Technologies”), work through three tabs:

• Platforms — Illumina, Oxford Nanopore, PacBio, and so on
• Devices — specific instrument models, each tied to a platform
• Accessories — sub-tabbed into Flow Cells, Kits and Software

Until this registry has entries, the Sequencing Technology field on the order form has nothing to offer researchers, and pipelines that need a platform family (MAG derives its short_reads_platform column from it) have nothing to derive from.

Customise the sequencing order form

Settings → Sequencing Order Form (/admin/form-builder, titled “Sequencing Order Configuration”) controls what researchers see. The shipped default gives them two question steps — Sequencing Order Details (Sequencing Order Name, Number of Samples) and Sequencing Information (Sequencing Technology, Library Strategy, Library Source) — followed by Samples and Review.

The page has five tabs: Per-Sequencing Order Fields, Per-Sample, Facility Fields, Settings and Import / Export. Field edits auto-save; the header tells you whether it has caught up.

Three things worth doing now rather than later:

1. Delete fields you never use. Removing a field after orders have used it leaves orphaned values in Order.customFields.
2. Mark facility-only fields admin-only. Each field row has a Move this field to Facility Fields action; from then on they live on the Facility Fields tab here, researchers never see them, and admins edit them through the order’s own Facility Fields view even after submission. The default form already ships four: Internal QC Status and Internal Notes at order level, plus Sample QC Result and Sample Notes per sample.
3. Write the post-submission instructions. On the Settings tab, under Advanced Settings → Post-Submission Instructions, is the text researchers see after they submit — where to ship samples, what to label them with, what to include in the package. It is a Markdown editor with its own Save Instructions and Reset to Default buttons, separate from the field auto-save.

Study metadata forms live under Settings → Study Forms, or Define Studies when the dynamic-studies module is on.

Set up data storage

A shell operator can configure and verify the installer-created starting directory first:

seqdesk storage configure "$HOME/seqdesk/data"
seqdesk storage status

Use the facility’s existing absolute sequencing directory instead when one is already mounted. The CLI validates the path and keeps the installed settings file and database setting synchronized.

The Infrastructure page (/admin/data-compute) is a hub: it links out to Open Data Storage and Open Pipeline Runtime, and carries the Import settings.json box. To configure through the UI, follow Open Data Storage (/admin/data-storage) and fill in:

Finish with Save Data Settings — Test Path only checks, it does not store anything.

Scan depth is not on this screen. It is sequencingFiles.scanDepth in settings.json (or SEQDESK_FILES_SCAN_DEPTH), defaults to 2, and is rejected outside 1–10. That makes the layout you pick load-bearing: a base path of /data/sequencing with run folders directly inside it works at the default depth, while FASTQ files buried five levels deep are invisible until you edit the config file and restart.

Configure pipelines (optional)

Pipelines are off unless the host was installed with --with-pipelines or pipelines.enabled is set in settings.json. The core application — orders, samples, studies, ENA submission — runs fine without them.

Once enabled:

1. Settings → Infrastructure → Pipeline Runtime (/admin/pipeline-runtime). Everything below is in Required Configuration unless marked otherwise.
2. Use SLURM is a switch, not a mode dropdown: off means local execution, on reveals Queue/Partition.
3. Set the Pipeline Run Directory. This is a required readiness check, and it should live on different storage from your sequencing reads — Nextflow work directories are large and disposable.
4. Set Conda Installation Path and Conda Environment Name (execution is Conda-based).
5. For SLURM, open Advanced Configuration for CPU Cores, Memory and Time Limit (hours) — hours, not minutes — plus extra sbatch options. Nextflow Weblog URL is there too; it is the recommended readiness check.
6. Install and enable individual workflows under Settings → Pipelines (/admin/settings/pipelines), which splits them into Per-Sample Pipelines and Per-Study Pipelines.

Set up ENA credentials (optional)

If you plan to publish to the European Nucleotide Archive, go to Settings → Data Upload (/admin/ena, titled “ENA Configuration”) and work down the ENA Connection card in the order the fields appear:

1. Leave Submission server on Test. The control is a Test/Production switch: Test points submissions at wwwdev.ebi.ac.uk, which accepts the same XML and issues throwaway accessions. Flipping it to Production raises a warning banner in place.
2. Enter your Webin username (format Webin-XXXXX) and Webin password, then press Test connection.
3. Leave Center name alone unless you have a broker account. The field stays disabled until the Broker account switch is on, because ENA takes the affiliation from the Webin account for regular submitters; only a broker writes its own center_name into the XML. Turning broker mode on and leaving the name blank blocks the save with Enter a center name or disable broker account mode.

The Upload Readiness strip at the top of the page scores four things — Credentials, Server, Account and Submissions — and is the quickest way to confirm all of the above landed. Note that it deliberately flags Server amber once you are on production: that is a reminder, not a fault.

Get one complete study through the test server before switching to production. A production registration cannot be withdrawn.

Check the background workers

Settings → Background Workers (/admin/background-workers) shows status, recent log output, and start/stop controls for the long-running daemons: the Pipeline monitor and the MinKNOW stream monitor. Without the pipeline monitor, runs are still created and launched, but their status only advances when a Nextflow weblog callback arrives — the monitor is what recovers status from queue and trace state when callbacks cannot reach the app.

Two things to know before you press anything:

• The pipeline monitor starts itself. SeqDesk boots it on every server start, including after an in-app update, and stops it again on a clean shutdown. You should find it already RUNNING. Set SEQDESK_DISABLE_WORKER_AUTOSTART=1 to opt out.
• The stream monitor does not. Start it here if you are ingesting live MinKNOW output; it is the daemon the order’s Stream view depends on.

Reported status is reconciled against the operating system on every read, so a worker whose process died shows as stopped rather than as a stale RUNNING.

Review what arrived

The order appears on your Sequencing Orders page — as an admin you see every order in the instance, not just your own. Open it and check the sample metadata and the sequencing parameters.

You can edit the Facility Fields on the order and its samples at any time, including after submission. Researchers cannot see or edit those.

Attach the FASTQ files

Open the order’s Sequencing Data area. Its sub-navigation is Overview, Associate and Stream, and three routes exist:

• Associate (also reachable from the Associate Files button on Overview, and titled “Discover & Associate”) browses the configured data directory, lists candidate FASTQ files, recognises _R1/_R2 (and _1/_2) naming to pair them, and links them to samples.
• Upload Files is a dialog on the Overview that pushes files into the order directly.
• Stream attaches a live MinKNOW run for Oxford Nanopore, ingesting reads by barcode as they are written. This needs the stream monitor from Background Workers to be running.

File assignment requires the order to be SUBMITTED or COMPLETED. On a DRAFT order the API answers Sequencing Order status 'DRAFT' does not allow file assignment, and if the storage path is unset it answers Data base path not configured.

Once every sample in the order has at least one read with a file, SeqDesk flips the order to COMPLETED automatically and writes a status note saying so. You do not have to do it by hand.

Classify the reads

Every read carries a data class: cleaned, raw / protected, or unknown. Only reads that are cleaned and active are ever handed to the requesting researcher. Reads that still contain host or contaminant sequence should be marked raw; the read-cleaning pipeline can then produce a cleaned successor, which supersedes the original while keeping the provenance chain.

Publish the delivery

Attaching files does not make them visible to the researcher. On Sequencing Data → Overview there is a Delivery to user card. Press Make downloadable to user and confirm in the dialog it opens.

If the button is disabled or the API answers No cleaned reads or customer-facing reports are available to publish., the cause is almost always unclassified reads — unknown counts as protected. Hide from user reverses the publication at any time.

Create a study and run analyses

Go to Studies, create one, and assign the relevant samples. Remember that a sample belongs to at most one study, and that a study can pull samples from several orders.

Each installed pipeline package declares which catalogue it belongs to, and the app shows it only where it fits. Of the shipped packages, MAG, Quality Overview, Study MultiQC, Study Demo Report and Submit to ENA are study-scoped and launch from the study’s Analysis tab; Simulate Reads, FASTQ Checksum, FastQC, NanoPlot and Read Cleaning are order-scoped and launch from the order’s Analysis view. Taxonomic Profiling (Kraken2 + Bracken) declares both, so it appears in each. Only admins can start any of them.

Publish the results

A completed run is still invisible to the researcher. Open the run’s menu and choose Use as final; it gains a Final badge and appears in the owner’s Analysis view. Clear final reverses it.

Only completed runs can be selected — otherwise the API answers Only completed pipeline runs can be selected as final. Exactly one run can be final per pipeline per target, so marking a re-run final replaces the previous one in the researcher’s view. That is the intended way to correct a bad run.

Generate an invite code

Settings → Accounts (/admin/admin-accounts) → create a new invite code. You can restrict it to a specific email address and set an expiry.

Share the code

The new admin registers at /register/admin, enters the code to verify it, then creates their account (minimum 6-character password). The invite is single-use; a second attempt gets This invite has already been used. An expired code gets This invite has expired, and a code restricted to another address gets This invite is for a different email address.