seqdesk doctor

seqdesk doctor is a diagnostic subcommand of the seqdesk npm launcher. It walks an installed SeqDesk directory and prints a pass/warn/fail report covering the install layout, the runtime configuration, the database connection, and (if a URL is supplied) a small set of HTTP probes against the running app.

It does not modify anything. Run it as often as you like — after install, after an update, or whenever the app behaves oddly.

Usage

seqdesk doctor [--dir /path/to/seqdesk] [--url http://127.0.0.1:8000] \
  [--timeout-ms 5000] [--json] [--help]

If --url is not supplied, doctor tries to derive one from runtime.nextAuthUrl (or app.port) in seqdesk.config.json. If neither is set, the HTTP checks are skipped with a warning.

Checks

Install layout

Pass the installation root to --dir, not the current/ symlink. Distribution installs keep shared configuration at the root and immutable application files under current/; doctor checks both locations automatically.

Runtime configuration

Read from seqdesk.config.json (runtime.* section, with flat-key fallbacks):

Known limitation: socket-only databases

The PostgreSQL TCP check opens a TCP socket to the URL’s host and port. It has no Unix-socket mode, so it cannot verify a database reached through a socket directory — which is exactly what an install with a SeqDesk-managed cluster (or a reused local socket) uses. Those installs carry a URL such as:

postgresql://seqdesk:...@localhost:5432/seqdesk?schema=public&host=%2FUsers%2Fyou%2F.seqdesk%2Fpostgres%2Fsocket

Doctor probes localhost:5432, finds no listener, and reports error PostgreSQL TCP - localhost:5432 unreachable, which makes the whole run exit 1 even though the installation is healthy. Verify a socket-based database directly instead:

PGROOT="${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}"
pg_ctl -D "$PGROOT/data" status
pg_isready -h "$PGROOT/socket"

Every other check in the same report — layout, configuration, and the HTTP probes, including /api/setup/status, which exercises the real application database connection — stays meaningful. Do not treat this single failure as a reason to recreate the database or reinstall. Because of it, do not gate CI on doctor’s exit code for socket-based installs; use --json and inspect the individual checks, or gate on /api/setup/status.

HTTP probes (when a URL is available)

When a URL was inferred (not passed via --url), an unreachable endpoint is reported as a warn, since the app may simply not be running. When --url was passed explicitly, the same failure is reported as a fail.

What doctor does not check

A clean doctor report means “the layout is intact, the configuration parses, and the app answers” — not “this installation is fit for production”. The full list of checks is above; everything below is outside it and needs its own verification.

Doctor is also read-only by design: it never repairs, migrates, restarts, or rewrites anything it finds wrong.

Output

Text (default)

SeqDesk doctor
Version: 1.1.x
Directory: /opt/seqdesk
URL: http://127.0.0.1:8000

Checks
  Install directory: /opt/seqdesk
  package.json: seqdesk@1.1.x
  settings.json: parseable
  start.sh: executable
  node_modules: present in current release
  .next/static: present in current release
  runtime.databaseUrl: postgresql://seqdesk@127.0.0.1:5432/seqdesk
  PostgreSQL TCP: 127.0.0.1:5432 reachable
  warning runtime.directUrl - missing; databaseUrl will be used as fallback
  runtime.nextAuthUrl: http://127.0.0.1:8000
  runtime.nextAuthSecret: set
  warning telemetry - disabled
  HTTP /api/auth/providers: credentials auth available
  HTTP /api/setup/status: database configured

Summary
  Passed: 12
  Warnings: 2
  Errors: 0

Pass checks render as name: detail. Warnings render as warning name - detail and failures render as error name - detail.

JSON (--json)

The same data, structured for scripts:

{
  "version": "1.1.x",
  "installDir": "/opt/seqdesk",
  "appUrl": "http://127.0.0.1:8000",
  "checks": [
    { "name": "Install directory", "status": "pass", "detail": "/opt/seqdesk" }
  ],
  "summary": { "pass": 12, "warn": 2, "fail": 0 }
}

Exit codes

This makes doctor safe to run in CI and post-install hooks — wire it as a non-zero gate without parsing the text output, except on an installation whose database is reached over a Unix socket, where the TCP-check limitation makes exit 1 the normal result. Gate those on --json plus a per-check inspection instead.

Acting on failures

Doctor is read-only and identifies the failing layer; it does not repair or migrate the installation.

After correcting the reported layer, rerun the same doctor command. Use the Quickstart troubleshooting checklist for host installs, or the platform-specific sections for Linux, macOS, and AWS EC2.

When to run it

• After a fresh install — confirm the layout is intact and the database is reachable before logging in for the first time.
• After an update — see Automatic Updates. If the app fails to come back up, doctor narrows the failure to layout, DB, or HTTP.
• In CI — run seqdesk doctor --json against a freshly provisioned instance to validate the install pipeline.
• When troubleshooting — failures point at exact files and ports, which is usually faster than reading the app logs from scratch.

Manual install checklist

The seqdesk npm tarball ships a MANUAL_INSTALL.md checklist that walks through provisioning a fresh Linux machine, installing SeqDesk, starting the app, running doctor, verifying telemetry, and cleaning up. Use it for end-to-end manual smoke tests before relying on a new host.