Docker and NAS

The published image is ghcr.io/alexphillips-dev/gearbeacon, with linux/amd64 and linux/arm64 variants. Use the repository's Compose file as the starting configuration. Keep it in a persistent project directory on your Docker host; source users can run these commands from the checkout root.

Start with Compose

docker compose up -d
docker compose logs gearbeacon

Compose uses the published image by default and contains a build definition for local builds. Open http://localhost:8787 on the Docker host and use the one-time token printed in the logs to complete owner setup. The default port mapping is 127.0.0.1:8787:8787, so another device cannot connect directly to it.

To explicitly build a source checkout:

docker compose build
docker compose up -d --no-build --pull never

Persistent storage and runtime protections

Setting	Shipped behavior
Application data	/data, persisted in the gearbeacon-data named volume
Process access	Authenticated private mode, listening on 0.0.0.0:8787 inside the container
Published host port	Loopback only
Filesystem	Read-only root; writable data volume and constrained /tmp tmpfs
Process restrictions	Unprivileged user, all capabilities dropped, no-new-privileges, PID limit
Restart policy	unless-stopped

Compose normally prefixes a named volume with the project name. Moving the Compose project, changing its name, or switching volume definitions can attach a different empty volume. Preserve the actual volume identity during updates. Do not use docker compose down -v for routine maintenance: it removes named volumes and can delete your saved data.

For a NAS bind mount, the container user must be able to write the mounted directory. Preserve the supplied container restrictions and verify storage access in Settings > Operations. Mount application data on storage suitable for SQLite; use separate mounted storage for recovery copies rather than sharing one live database between containers.

Configuration and version pinning

The browser is the normal place to configure regions, polling, notifications, and backups. A project-local .env file supplies variables referenced by Compose, for example:

GEARBEACON_IMAGE_TAG=1.2.0
REGIONS=us,ca
GEARBEACON_TIME_ZONE=America/New_York

Use the intended released version; latest is the default if the tag is unset. Settings already saved in GearBeacon generally take precedence over environment defaults. The provided Compose configuration defaults scheduling to UTC, while native installations default to the host timezone.

Compose does not automatically forward every .env variable into the container. It only interpolates values referenced by the Compose file. Check its environment mapping before adding a setting; for example, its POLL_SECONDS is explicitly set to 60. An additional process-level variable needs an explicit mapping. See Configuration reference.

Access from another device

Use a trusted LAN/VPN or a restricted HTTPS reverse proxy. For direct private access, edit the existing ports entry to bind the intended host interface instead of loopback. This is an example structure, not a literal address to use:

ports:
  - "YOUR_PRIVATE_HOST_IP:8787:8787"

Replace YOUR_PRIVATE_HOST_IP with the host's appropriate private/VPN interface and restrict its firewall sources. Keep authenticated private mode inside a bridged container. Do not switch the container to local mode to avoid owner setup.

Native proxy mode requires a loopback backend connection. A normal Docker bridge connection does not satisfy that condition, even if the host publishes only to loopback. The reverse-proxy guide explains using a restricted host proxy with private-mode Docker and the difference in forwarded-header handling.

Secondary backups

Mount a second destination into the container, for example /recovery, then use that container path in Settings > Data. A host path that is not mounted is unavailable to GearBeacon. The container user needs write access, and the mount should already be present before backup scheduling starts.

Choose validated SQLite copies or encrypted recovery exports, create a backup, and test both primary and secondary restores. An encrypted secondary export excludes local integration secrets; keep the installation key separately if you also retain SQLite backups. See Backups and recovery.

Maintenance

docker compose ps
docker compose logs --tail 100 gearbeacon
docker compose stop gearbeacon
docker compose start gearbeacon

Use the appropriate command individually. Logs can contain the setup token and local details; use the application's redacted support bundle for public troubleshooting.

For an update, first prepare a validated backup in GearBeacon, set the desired image tag persistently in .env, then pull and recreate the service. The current development helper persists the chosen tag in the project .env, verifies the running image and local startup version, and reports failures with recovery instructions. Older helper copies export the tag only for their invocation, so persist it manually for those versions. Current helper changes are not in published v1.2.0 archives. Full instructions are in Updates and rollback.