Operations

Where things live§

Everything HVNT33 writes at runtime is under data/, which Git ignores: in the repository when you run it from source, or in the app's data folder when an installed app has no workspace chosen. Set HVNT33_DATA_DIR to keep it elsewhere.

The built-in database listens on a free port on this machine only (see data/arcadedb/instance.json); you never need to reach it directly. The server creates the database and indexes automatically.

Server modes and configuration§

The server runs in local mode by default. Token mode is the hosted shape: API tokens, isolated workspaces and plan limits. See apps/server/README.md for npm run admin and plan configuration.

The schema is versioned: migrations in apps/server/src/db/migrations.ts apply at startup (recorded in SchemaMigration), so upgrading is restarting the server. Take a backup first; migrations only add.

Moving from the Docker database§

Earlier versions ran ArcadeDB in Docker, on the same data/arcadedb/databases/ folder. To move to the built-in database:

1. Quit the app and stop npm start, then stop the container so ArcadeDB closes its files: docker stop hvnt33-arcadedb.
2. Copy data/arcadedb/databases/ aside as a backup.
3. Delete the ARCADEDB_URL and ARCADEDB_USER lines from .env (keep ARCADEDB_PASSWORD: the built-in database takes it on first start).
4. Start HVNT33. The built-in ArcadeDB opens the same files; it is a newer version and reads databases made by the old one.

When everything is there, remove the container and its configuration volume: docker rm hvnt33-arcadedb and docker volume rm osint_arcade-config.

Updating the built-in database§

npm run runtime:update pins the newest Temurin JRE and ArcadeDB release (checksums from Adoptium and ArcadeDB's GitHub releases), and npm run runtime:fetch installs them. Take a backup first, run npm test, then restart the app. ArcadeDB opens databases made by earlier versions.

Snapshots: your own archive§

A snapshot stores a page as a WACZ web archive, its readable text, a screenshot and a manifest of their SHA-256 hashes, and asks independent timestamp authorities to sign the manifest's hash. Snapshots are taken on request ("Snapshot now"), with a capture, or on a schedule for watched pages.

In the app, snapshots are made by its own browser: a hidden window loads the page in a fresh session (no cookies or sign-ins), through the case's route when it has one, and records every response it receives (the document, scripts, styles, images), then scrolls through the page so lazy content loads and takes a screenshot and the rendered text. The archive replays the page as it rendered. A snapshot takes 5 to 30 seconds. A server running without the app fetches only the page's HTML: text and change tracking work, but the archive has no images or styles and no screenshot, and the snapshot says so in its notes.

To check an evidence package without HVNT33, follow its VERIFY.txt: shasum -a 256 -c SHA256SUMS, then openssl ts -verify for each token. DigiCert tokens verify against the system CA bundle; FreeTSA publishes its CA at https://freetsa.org/files/cacert.pem. Timestamp requests send only a hash, never page content or URLs. If no authority can be reached, the snapshot is still stored and records why it has no timestamp.

A hosted deployment adds its own capture implementation (a headless browser on workers whose network cannot reach private addresses); the server itself refuses private addresses for the starting URL and every redirect of direct fetches.

Make a recovery backup§

npm run backup

This creates an ArcadeDB snapshot, then packs it with the evidence vault and a manifest into data/exports/. Originals are append-only, so the vault may include files captured after the database snapshot; files referenced by the snapshot are retained. A recovery ZIP contains private research. Keep a copy on separate storage. Presentation exports are portable components, not native database recovery backups.

Restore without overwriting your current database§

Quit the app (or stop npm start), then restore into a new database name:

npm run restore -- data/exports/hvnt33-backup-….zip newsroom_restored

It refuses a name that already exists and a database that is still running. Evidence files from the backup are added to data/vault/; files already there are kept (originals are append-only). Set ARCADEDB_DATABASE=newsroom_restored in .env and start HVNT33 again. Your original database remains available under its original name. Credentials are not in the recovery ZIP; the database keeps its own. The backup and restore round trip is checked against ArcadeDB's own restore tool, bundled with the built-in database.

Security and scale§

The server uses ArcadeDB's authenticated HTTP API; credentials stay on the server. IDs are uniquely indexed, and records, connections, intakes and search runs are indexed by investigation, so cases remain independently queryable. Uploads and exports stream to disk or network rather than holding whole files in memory. The graph display is bounded to 70 matching nodes; CSV and JSON exports include the complete selection.

This is a usable single-user version, not a benchmarked multi-user deployment. The web interface fetches a complete investigation and searches it locally. For very large cases, the next scaling work is server-side full-text search, paginated records, neighborhood graph queries, background ingestion and resumable uploads (see ROADMAP.md). There is no OCR, transcription, multi-user authentication, encryption layer or general edit-history ledger yet.

The server and the built-in database bind to localhost. Other users and processes on your machine can reach them; use a protected account and encrypted storage for sensitive work. Do not expose this version to the internet. The desktop app's own security model is described in apps/desktop/README.md.

Tests§

ArcadeDB integration follows the official HTTP API and backup/restore documentation. The built-in version is pinned in apps/server/vendor/runtime.json.