Backups and Recovery

GearBeacon stores live state outside its application directory. Back up the database, retain the installation encryption key, and test recovery before an update or host move. A validated primary backup and a second copy on separate storage protect against different failures.

Default data locations

Installation	Data directory
Windows portable/source	%LOCALAPPDATA%\GearBeacon
Windows automatic-start installation	%ProgramData%\GearBeacon
macOS portable/source	~/Library/Application Support/GearBeacon
macOS LaunchDaemon	/Library/Application Support/GearBeacon
Linux portable/source	${XDG_DATA_HOME:-~/.local/share}/GearBeacon
Linux systemd service	/var/lib/gearbeacon
Docker	/data in the persistent volume

GEARBEACON_DATA_DIR can override the process path. Operations shows the actual active data location; do not assume a portable process and installed service use the same one.

The directory contains gearbeacon.sqlite3, its SQLite sidecar files when present, backups/, and secrets.key. Mock mode uses gearbeacon.mock.sqlite3. Databases, keys, exports, sessions, and logs are private data and do not belong in Git or public support attachments.

Choose recovery material

Material	Restores	Extra requirements
Validated SQLite backup	Database state, including owner credentials and locally encrypted integration settings	Matching secrets.key to decrypt saved integration secrets; compatible application schema
GearBeacon JSON recovery export	Exported watches, history, collection plans, configuration/preferences and related recovery state	Reconfigure excluded owner credentials, sessions, and local integration secrets as needed
Passphrase-encrypted export	Same portable recovery content, encrypted with AES-256-GCM and a scrypt-derived key	Export passphrase; it does not recover excluded integration secrets
Redacted support bundle	Diagnostic evidence only	Not a backup and cannot restore an installation

Losing secrets.key does not erase watches or history, but encrypted notification credentials must be entered again. An encrypted export's passphrase and secrets.key serve different purposes; keep required recovery material securely outside the primary failure domain.

Create and test primary backups

In Settings > Data, choose backup interval and retention, then Create backup now. Defaults are every 24 hours and ten retained backups. A zero interval disables scheduled backups, not the manual or migration-safety controls.

Backups check SQLite integrity, create a consistent VACUUM INTO snapshot, and check the snapshot again. GearBeacon creates a validated safety backup before schema migrations and imports; Prepare safe update also creates a pre-update backup.

Select Test latest primary. Restore tests open a temporary copy, validate its integrity/format and schema compatibility, and leave the live database unchanged. Repeat after upgrades or storage changes. A test proves the tested file can be read and validated, not that every aspect of a replacement host has been rehearsed.

Secondary storage

1. Mount a separate disk/share or Docker volume and make it accessible to GearBeacon's actual service/container identity.
2. Set an absolute destination in Settings > Data. Keep it separate from the primary data tree; symbolic-link destinations are rejected.
3. Choose SQLite copies or encrypted recovery exports. For encryption, first save a passphrase of at least 12 characters in the browser.
4. Create a backup, verify the secondary result in Operations, then choose Test latest secondary.
5. Securely retain the export passphrase and, for SQLite recovery of saved credentials, the matching installation key.

GearBeacon verifies destination access and warns if it appears to share the primary filesystem. A secondary-copy failure reports a warning while preserving a successful primary backup. Test again after permission, mount, host, or container changes.

Linux systemd installations need a writable-path drop-in as well as filesystem permissions; see Linux installation. Docker uses the mounted container path. Windows startup tasks and macOS daemons may not see a drive/share mounted only in your interactive desktop session.

Restore an export through the browser

Use a fresh or existing compatible installation with working owner access. In Settings > Data, preview the recovery file, provide the passphrase for an encrypted export, review its contents, and explicitly confirm the import. Treat this as recovery, not the separate Watchlist import that merely adds products.

Preview/import support request bodies up to 256 MiB. An HTTPS proxy may need a matching body-size allowance. Keep the pre-import safety backup, review configuration afterward, re-enter excluded notification secrets, and restart if restored process settings require it. Test channels and allow a fresh complete Store check before interpreting readiness.

Restore SQLite or move an installation

1. Identify the correct source and destination data directories and the backup's compatible application version. Test the recovery file first where possible.
2. Stop every GearBeacon process/task/service/container using the data directory. Do not copy a running SQLite file as though it were a consistent backup.
3. Preserve the stopped destination's existing database and any -wal/-shm sidecars together as a separate recovery set. Do not mix stale sidecars from that set with the restored database.
4. Put the tested SQLite snapshot in the destination as gearbeacon.sqlite3, with its matching secrets.key if recovering saved integration credentials. Preserve restrictive permissions for the intended service identity.
5. Start the same or a schema-compatible newer application. Verify owner access, watches, collection plans, storage health, and channel tests in Operations.

For a host move, stop the old instance before allowing the new one to monitor and deliver alerts. For rollback, restore an older compatible database and application together; replacing only the executable may leave it unable to read the schema. See Updates and rollback.

Current dev compatibility

Budget-aware collection alerts add schema v12 and recovery export format v8 in the current dev checkout. Startup creates and validates a safety backup before migrating an existing database, including from published v1.2.0/schema v11. Existing collections retain their plans and alerts with the new condition off. Plain/encrypted exports preserve budgetRequired; older supported exports default it off. Restart the server after updating to activate the new API.

The published v1.2.0 binary cannot open the newer database or format-v8 export. To return to that build, stop GearBeacon and restore its compatible pre-update database with the matching secrets.key, then start the older application. Do not point an older binary at the migrated live database.

Version 1.2.0 compatibility and retention

Upgrading to GearBeacon 1.2.0 creates a validated safety backup before schema v11, including when updating from an earlier 1.2.0 build. Restart the GearBeacon process after updating so the migration and new API are active. Existing watches, rules, collections, and history are retained. Existing members start with one desired unit, preserve their watch's purchased state, and have unknown actual purchase costs; budgets are unset and collection-only mode is off. Existing collections start active; upgrades from schema v10 preserve all purchase plans. Format-v7 recovery exports retain archive state, purchase plans, budgets, alert modes, inventory intervals, monitoring coverage, and readiness state. Preview and import accept requests up to 256 MiB; earlier formats remain supported with defaults for fields they did not record. Restoring an export cancels obsolete queued collection alerts and individual jobs suppressed by restored collection-only modes, and requires a fresh complete check before readiness is known. For rollback, stop the service and restore the compatible pre-upgrade database with its matching encryption key: older builds cannot open a schema-v11 database or format-v7 export.

Product/insight history defaults to 365 days and Activity retention is independently configurable; Activity retention 0 means indefinite retention. Stock/coverage interval tables also have bounded record counts. See Stock insights for the effect on charts and summaries.