Updates and Rollback

GearBeacon checks for releases and prepares backups, but never silently downloads or installs an application update. Choose the target version and follow the procedure for the installation you actually use.

Helper changes described as current checkout below are unreleased development work. The scripts bundled inside the published v1.2.0 archives retain their original behavior; those older helpers require manual startup/version verification.

Current dev database compatibility

The current dev checkout adds budget-aware collection alerts using schema v12 and export format v8. Startup validates a pre-migration backup; published v1.2.0 remains schema v11/format v7. Rolling back from dev to that release requires its compatible pre-update database and matching key, as well as the older executable/image. See recovery compatibility.

Prepare every update

1. Open Check for updates, review release notes and schema/recovery requirements, and confirm the running version/build in Settings > Operations.
2. Select Prepare safe update. It flushes current regional state and creates a validated pre-update SQLite backup.
3. Confirm the backup succeeded, retain its matching secrets.key, and test recovery. Keep a recovery copy outside the application directory; a secondary copy helps with primary-disk failure.
4. Run the applicable update procedure below. Use a version such as 1.2.0, without a leading v, for helper arguments.
5. Restart GearBeacon and refresh the browser. Verify the version/build, database health, watches, collection plans, fresh region checks, and notification configuration.

Do not replace a running executable or let two instances share the data directory. A refreshed browser alone does not activate a new backend or database migration.

Installed Windows task

From the extracted standalone package, in elevated PowerShell:

.\update-windows.ps1 -Version 1.2.0 -BackupConfirmed

Use your reviewed target version. The helper downloads the matching Windows archive, verifies SHA-256, stops the GearBeacon scheduled task, replaces the application binary/web/manifest, and starts the task. Its default application path is %ProgramFiles%\GearBeacon; use -InstallDir if installed in a supported custom location.

Installed macOS or Linux service

From the extracted standalone package:

./update-mac-linux.sh 1.2.0 --backup-confirmed

The helper selects the operating system and architecture, downloads/verifies the matching archive, and uses administrative commands to stop the daemon/service, replace the binary/web/manifest, and restart. Its installed paths are /usr/local/lib/gearbeacon on macOS and /opt/gearbeacon on Linux.

Current checkout native helpers also replace build-info.json when supplied by the archive, then poll local /healthz for the expected application/package version. They check liveness independently of Store readiness, so an upstream outage does not by itself fail startup verification. The default port is 8787; use -Port 9876 on Windows or --port 9876 on macOS/Linux for a custom port. Verification defaults to 60 seconds and accepts -TimeoutSeconds or --timeout-seconds from 1 to 300. Linux/macOS also supports --install-dir pointing to an existing directory named gearbeacon; Windows uses -InstallDir ending in GearBeacon.

A failed stop, install, restart, or verification returns an error; a failure after service changes prints recovery guidance. Do not interpret that as a successful update or an automatic rollback. Inspect service/task logs and the selected port before deciding whether to recover. Startup verification does not prove every monitoring or notification path works.

Native helpers update application files. They do not automatically re-run every installer or replace all service/helper configuration. Review release notes for deployment changes and apply an updated installer deliberately when required, preserving custom configuration and data.

The checksum establishes consistency with the release's checksum file; it is not a native code signature. SBOM and GitHub provenance are separate release metadata.

Portable standalone installation

After preparing the backup, stop the foreground process. Download and verify the target platform archive, extract it into a fresh application directory, and start its executable with the same intended data-path configuration. Keep the executable, web, and manifest together.

The native service updaters target installed services/tasks; they are not required for a portable copy. Retain the previous application package for rollback, and leave external live data in its existing location unless intentionally migrating it.

Source checkout or source archive

After backup preparation and stopping the process, update a clean checkout of your intended branch with:

git pull --ff-only

If local changes or divergence prevent this, preserve them and review the difference before updating; do not discard them to force a pull. For a fixed published version, use its complete verified source archive in a fresh directory instead. Published compiled output can run without rebuilding; local TypeScript changes require the documented build/check workflow.

Restart using the launchers included with that checkout/archive. The v1.2.0 source ZIP has root-level launchers, while the current checkout uses launchers/; see Source installation.

Docker / NAS

Keep the same Compose project and persistent data volume. Set the reviewed target tag in the project's .env first:

GEARBEACON_IMAGE_TAG=1.2.0

Then, after successful backup preparation:

docker compose pull gearbeacon
docker compose up -d --no-deps gearbeacon
docker compose ps

Alternatively, from the Compose project directory use the repository helper:

./deploy/update-docker.sh 1.2.0 --backup-confirmed

The current checkout helper prepares a private temporary .env, preserves unrelated entries/comments, replaces existing GEARBEACON_IMAGE_TAG assignments, and atomically installs the file after the image is pulled. It verifies that Compose resolves the service to the requested official image, that the running container uses the pulled image ID, and that local /healthz reports the expected base version. This image-ID check also identifies prerelease images whose application version is the stable base number. An optional third argument sets the startup timeout in seconds (default 60, range 1–300).

Run from the Compose project directory with the normal project .env; custom COMPOSE_ENV_FILES or disabled .env loading are rejected. Shell environment variables and later Compose overrides can still supersede the file. The resolved-image preflight uses Docker's documented Compose config command. The helper creates an update lock; if interruption leaves it behind, establish that no update is running before removing .gearbeacon-update.lock.

If pull/preflight fails, .env remains unchanged. If restart/verification fails after pinning, the requested tag stays in .env and the helper prints recovery instructions; it does not silently revert files or data. Older helper copies export the tag only for their invocation, so persist it manually for those versions. Do not remove/recreate the data volume or use down -v for an update.

Rollback

1. Stop the upgraded process/service/container and preserve its stopped database/sidecars and logs as a separate recovery set.
2. Select the previous known-good application or image version.
3. Restore the tested pre-upgrade database compatible with that version, retaining the matching secrets.key. Avoid mixing old WAL/SHM sidecars with the restored snapshot.
4. Start the previous version and verify integrity, owner access, watches, rules, and channels.

GearBeacon 1.2.0 uses schema v11 and recovery export format v7. An older build that lacks support cannot open that database/export. Rolling back only the executable/image is insufficient. A rollback to an earlier backup also rolls saved state back to the time of that backup.

Detailed data locations and restore safeguards are in Backups and recovery. If an update fails before completion, inspect Operations/startup logs and preserve the backup before retrying.