Automatic Updates

SeqDesk includes a built-in update system in the admin panel. It stages each new release into its own directory, runs migrations, and activates the release by swapping an atomic current/ symlink — keeping the previous release available for an instant rollback.

Update Flow

Check for updates

The admin UI at Admin → Settings → Software Updates shows the running and installed versions and checks the update server. Use Check now to force a fresh check:


GET /api/admin/updates?force=true

The check returns:

Running version and installed version (and whether a restart is required)
Latest available version and whether an update is available
The current database provider and whether it is compatible with the release

Check results are cached for 1 hour; each non-forced check also sends an anonymous telemetry heartbeat (running/installed version, update availability, database provider). Telemetry can be disabled — see Operational Telemetry.

Compatibility gate

Before installing, the server verifies the release is compatible with the configured database. If a release requires PostgreSQL and the install is not on PostgreSQL, the install request is rejected with HTTP 409 and is never started.

Disk space check

The system verifies at least 150 MB of free disk space before downloading.

Download and verify

The release tarball is downloaded from the configured update server (default: https://seqdesk.com) and its SHA-256 checksum is verified.

Stage the release

The tarball is extracted into a staged release directory. Production dependencies (npm ci --omit=dev) and the Prisma client are installed in the staged tree, away from the live application, so the running version is never disturbed while the update is being prepared.

Activate (atomic symlink swap)

Shared runtime paths are linked into the staged release, the staged tree is published as releases/<version>, and the current/ symlink is atomically switched to point at it. The previously active release directory is retained for rollback.

Run migrations

Database migrations run from the newly activated release using prisma migrate deploy (forward-only). Record counts for orders, samples, studies, and users are snapshotted before and after; if any count drops, the update aborts and the current/ symlink is switched back to the previous release.

Restart

The application restarts to load the new version. The updater tries, in order, pm2 restart, a user systemd service (systemctl --user), and a system systemd service (sudo -n systemctl); if none is available it exits non-zero so a process supervisor configured with Restart=on-failure relaunches it. Progress can be polled at:


GET /api/admin/updates/progress

Safeguards

Safeguard	Behavior
Database-compatibility gate	Install rejected with 409 if the release requires a backend the install does not have
Data-loss abort	Update aborts and reverts the symlink if order/sample/study/user counts drop after migrations
Atomic activation	`current/` symlink swap means there is no partially-overwritten install
Checksum verification	Downloaded tarball must match the published SHA-256

In-App Notifications

Facility admins receive in-app notifications when an update starts and as it progresses (including completion or failure), so the update can be followed without watching the progress endpoint.

Update Phases

Status	Description
`checking`	Preparing the update / verifying availability
`downloading`	Downloading and verifying the release package
`extracting`	Staging, installing dependencies, activating, and migrating
`restarting`	Application restart in progress
`complete`	Update finished successfully
`error`	Update failed (see error details)

Update Lock

Only one update can run at a time. The system acquires an update lock before starting; a second install or rollback request while one is in progress returns 409. The lock auto-expires after 1 hour so a crashed update cannot wedge the system permanently. When the target version is detected as both installed and running, the progress endpoint auto-completes the status and clears the lock.

Recovery Actions

When an update ends in error, the Software Updates panel offers:

Roll back release — one-click revert to the previous release (POST /api/admin/updates/rollback); shown only when a previous release is recorded. See Manual Update & Rollback.
Retry update — repair the active release in place (POST /api/admin/updates/install with { "repair": true }): reinstalls dependencies, regenerates the Prisma client, and re-runs migrations.
Clear failed status — discard the stale error state and release the lock.

Configuration

Setting	Description
`SEQDESK_UPDATE_SERVER`	Update server URL (default: `https://seqdesk.com`)

Troubleshooting

If an update fails:

Check the error message and phase in the Software Updates panel
Verify disk space and network connectivity to the update server
Run seqdesk doctor to narrow the failure to layout, database, or HTTP
Use Roll back release, or follow Manual Update & Rollback to re-point the current/ symlink by hand