Updates, backups, and recovery

Review releases, back up the full installation, test recovery, and complete an upgrade.

Maintaining Hunt Web means preserving both the installed application and its assessment data. A complete recovery checkpoint keeps accounts, original encryption keys, Browser profiles, Hermes conversations, Runs, evidence, and reports together. This guide explains the installed maintenance commands, the checks required before an upgrade, and common Desktop and Server issues. It applies to the supported Ubuntu 24.04 x86_64 installation.

1Review the release notesRead RELEASE-STATUS.md and check the package manifest.
2Prepare an idle windowPause scans, stop the Dashboard, and stop other writers.
3Back up the installationSave the manifest checksum separately from the backup.
4Verify and test recoveryVerify the archive, then restore into a new destination.
5Stage the upgradeCheck the package, existing source, and checkpoint.
6Complete the installationRun install.sh with the existing paths and settings.
7Check HealthSign in and check results and Hermes context on a test target.

Conceptual overview of the workflow.

1. Review Release Notes Before Updating

Read the incoming package's RELEASE-STATUS.md for distribution changes, supported platforms, compatibility notes, and known limitations. The bundled dashboard/CHANGELOG.md records Dashboard framework and component history; it is not a replacement for the distribution's upgrade procedure. CLI and Dashboard component version numbers can differ from the Hunt Web distribution version.

Obtain the publisher's canonical release archive and trusted package manifest checksum. The extracted package must match PACKAGE-MANIFEST.json, including file permissions. A Git working checkout, an already installed application, or a GitHub-generated archive is not automatically interchangeable with that upgrade package.

The commands below stage a selected release; they do not discover or install new versions automatically. Compatibility and dependency changes still need review, followed by an upgrade test on an isolated recovered installation.

2. Prepare an Idle Maintenance Window

Run maintenance commands from the installed application directory, using its original non-root runtime account. Record the application and data paths, runtime UID, current package identity, origin, ports, and service name:

./dashboard.sh status

Before taking the checkpoint:

1Pause scansLet result saving finish.
2Finish Hermes workThen close target Browsers belonging to this installation.
3Stop the DashboardUse dashboard.sh stop.
4Stop other writersCLI processes, Gateways, and scheduled maintenance.

Conceptual overview of the workflow.

Pause or stop scan work through the CLI or Dashboard and let result saving finish.
Finish or stop Hermes execution, then close target Browsers belonging to this installation.
Stop the Dashboard with ./dashboard.sh stop.
Stop separately launched CLI processes, Gateways, or scheduled maintenance that can write the same data.

Keep the installation offline throughout backup and upgrade. Stopping only the web page or Dashboard process does not establish that all writers have stopped. The backup helper checks active work and refuses a snapshot if included files change while being copied.

Paths under /srv below are examples. Their parent directories must already be writable by the runtime account. Private directories under that account's home are also suitable when substituted consistently. Backup and extraction destinations must be new, outside the application and data roots, with enough free space for both the archive and a full restore.

3. Back Up the Complete Installation

From the stopped installation:

./operations.sh backup --destination /srv/private-backups/checkpoint-001

Save the returned manifest_sha256 separately from the backup. It identifies this checkpoint and is required for verification and restore.

Data preserved by the backup	Purpose
Installed source, build, tool binaries and datasets, Python/Node/Hermes runtimes, and Chromium	Preserves the application and installed dependencies associated with the checkpoint.
Database, accounts, configuration, vault, and original encryption keys	Preserves access settings and the material needed to read encrypted data.
Targets, Scopes, Runs, requests, evidence, Findings, reports, and attachments	Preserves assessment records and their supporting files.
Hermes conversations and sessions, queues, execution receipts, Browser profiles, and logs	Preserves continuation context and operational history.

A database copy or downloaded PDF alone is not a complete recovery backup. Replacing a lost encryption key with a new key does not decrypt existing data.

Reproducible data/cache contents and transient top-level process/lock records are excluded. Custom external data locations or unsupported symlinks are rejected rather than silently skipped. OS packages, system Python, service units, DNS, reverse proxy, and Tunnel configuration require separate machine records or private checkpoints; the helper does not create an OS image.

Backups are not encrypted

The backup contains credentials and session material and is not an encrypted archive. Store it in protected, encrypted storage with an off-machine copy appropriate to the deployment. Keep it outside public source repositories, release packages, and support attachments.

4. Verify the Archive and Test Recovery

Replace RECORDED_CHECKSUM with the backup's saved manifest_sha256:

./operations.sh verify --backup /srv/private-backups/checkpoint-001 \
  --manifest-sha256 RECORDED_CHECKSUM

After successful verification, extract into a new private destination:

./operations.sh restore --backup /srv/private-backups/checkpoint-001 \
  --manifest-sha256 RECORDED_CHECKSUM \
  --destination /srv/private-restore/checkpoint-001

Restore checks archive contents, checksums, permissions, link boundaries, and SQLite integrity/schema. A completed extraction has RESTORE-RECEIPT.json; an interrupted extraction is not ready for activation. The checkpoint checksum detects changes against the recorded identity, not the authenticity of an untrusted source.

Successful extraction and successful operation are separate checks. The restored directory contains app/ and data/, still bound to the original absolute paths and runtime UID. Running their launchers at arbitrary new paths is not a supported relocation procedure.

For a recovery test, use a separate machine or an isolated filesystem setup that maps both restored roots to their original logical paths with the same UID and compatible OS. Keep the original installation inaccessible to the test instance. Changing only the port does not isolate the data. The package's docs/installed-recovery.md provides the recovery requirements.

Confirm login/MFA, permissions, saved Run IDs and Scopes, request/evidence readability, Findings, Report downloads, attachments, Hermes conversations, CLI operation, and access to encrypted provider configuration. Recheck target account access separately: a restored Browser profile can contain an expired session. The restore helper does not start services, Browsers, or scanning.

5. Stage and Complete an Upgrade

Once the candidate upgrade has passed an isolated test, take and verify a fresh checkpoint of the idle installation. Keep that installation unchanged until staging; the helper compares its contents against the checkpoint.

Use two distinct identities:

TRUSTED_PACKAGE_CHECKSUM: the incoming release's package manifest checksum.
RECORDED_CHECKSUM: the backup manifest checksum saved in the previous steps.

Replace /srv/packages/new-version with the clean extracted release directory:

./operations.sh stage-upgrade --package /srv/packages/new-version \
  --manifest-sha256 TRUSTED_PACKAGE_CHECKSUM \
  --checkpoint /srv/private-backups/checkpoint-001 \
  --checkpoint-sha256 RECORDED_CHECKSUM

Staging checks the incoming package, the existing owned source, and the checkpoint before replacing source files. Local source modifications require review; this procedure is not a merge of development changes. Only obsolete source files owned by the previous manifest are removed.

After staging succeeds, complete dependency, build, and database setup using the installation's existing paths and settings:

./install.sh --configure-later

A maintenance marker prevents Dashboard startup until installation succeeds. An interrupted installer needs completion or checkpoint recovery; deleting that marker is not a repair. Unsupported dependency transitions may require a fresh environment and a separately tested migration.

After installation completes, start the existing instance:

./dashboard.sh start
./dashboard.sh status

Review Health, log in with the existing account, and check saved results, Hermes context, and the required CLI/scan functions on a controlled test target. Preserve the existing Admin account and encryption keys during the upgrade. Starting or restarting the service does not automatically resume a scan or resend an instruction.

Desktop Health showing CLI configuration, database connectivity, saved reports, Hermes, and available scanner and Browser commands — Figure 1. Health describes the checks performed and the next steps. A Browser command being available does not prove a window opened or an account is logged in. Hermes connectivity does not test a model response. Counts reflect the example workspace.

6. Roll Back the Application and Data Together

If the upgrade fails, stop the installation and all associated writers. Preserve its failed application and data for diagnosis, then restore the verified pre-upgrade application and data as a pair. An older executable against a newer database is not a complete rollback.

1Stop everythingThe installation and all associated writers.
2Preserve the failed stateKeep the failed application and data for diagnosis.
3Restore the pairThe verified pre-upgrade application and data together.
4Cut overWith services still stopped, move the restored roots into place.
5Start one instanceRepeat account, data, and feature checks.

Conceptual overview of the workflow.

After validating recovery, cut over with services still stopped: preserve the failed roots at separate private paths, move the restored app/ and data/ to the original recorded locations, and restore the matching service configuration. The documented cutover uses controlled moves on the same filesystem, not copying over a running installation.

Start one instance and repeat account, data, and feature checks. Report the checkpoint time: changes made after it are absent unless preserved through a separate migration. Keep the checkpoint and diagnostic copy until recovery is accepted.

7. Manage Disk Usage and Retention

Installed dependencies, Chromium, tool datasets, scan evidence, logs, and backups all consume space. The installation guide budgets starting from 30 GiB free for installation/build, plus additional space for results, backups, and extracted restores. That starting budget is not a maximum or a guarantee of capacity for concurrent scans.

From the installed application directory, inspect memory and disk usage:

free -h
df -h . "$HOME/.local/share/hunt-web-v2"
du -sh . "$HOME/.local/share/hunt-web-v2"

Substitute the actual data path for installations using a different location. Run demanding builds, backups, and Browser tests sequentially on constrained machines, and measure storage before making large copies.

Use Settings → Storage & Retention and the relevant Trash, Restore, and Delete permanently controls. Saving retention rules alone does not immediately clean up records. Permanent Run deletion requires a recovery checkpoint if those results must be recovered later. Deleting a Hermes conversation retains its Run and results.

Backups are not automatically pruned. Review old copies only after a newer recovery has been proven. Do not treat database, vault, original keys, Browser profiles, or evidence directories as disposable cache. Stopping a service does not remove its application or saved data.