Configuration Reference

Most owners should use Settings. Environment variables seed new installations and support automated deployment; they are not a universal override of values already saved through the browser.

How configuration is applied

1. The process reads its environment and establishes defaults.
2. GearBeacon loads persisted application configuration and preferences from its database. Saved application settings take precedence over those defaults. Saved encrypted integration credentials also take precedence over their environment fallbacks.
3. Runtime values such as PORT, GEARBEACON_DATA_DIR, session lifetime, mock mode, and update-source URLs are process settings and require a restart to change.

Changing regions, access mode, or bind address in the browser saves the choice but requires one restart. Other supported operational settings apply immediately. Changing an environment value alone may therefore have no effect on a setting already saved in the app; check the browser configuration rather than deleting the database.

The source app does not load .env implicitly. See Source installation for node --env-file=.env. Docker Compose reads .env for interpolation but forwards only variables mapped into the service's environment. Service installers provide their own initial access/data defaults. The table below gives native application defaults unless stated otherwise.

Use 1 and 0 for boolean environment settings, comma-separated region/origin/recipient lists where documented, IANA timezones, and HH:MM local times. Start with .env.example, keep secrets out of Git, and prefer an owner password file to a plaintext command-line value.

Monitoring and process

Variable	Default	Purpose
PORT	8787	Dashboard/API port
REGIONS	us	Comma-separated us, ca, eu, uk
POLL_SECONDS	60	Poll interval; minimum 30 seconds
GEARBEACON_MIN_CATALOG_RATIO	0.55	Partial-catalog rejection threshold
GEARBEACON_STALE_AFTER_SECONDS	at least 180	Stale monitor threshold
MOCK_MODE	0	Offline demonstration catalog/database

Access and owner recovery

Variable	Default	Purpose
GEARBEACON_ACCESS_MODE	local	local, private, or proxy
GEARBEACON_BIND_HOST	mode default	Listening address
GEARBEACON_SETUP_TOKEN	random	Optional fixed one-time token
GEARBEACON_OWNER_PASSWORD_FILE	blank	Initial/recovery password file
GEARBEACON_OWNER_PASSWORD	blank	Initial/recovery password value
GEARBEACON_RESET_OWNER_PASSWORD	0	Apply configured recovery password and revoke sessions
GEARBEACON_PUBLIC_BASE_URL	blank	Canonical URL and notification link
GEARBEACON_SESSION_HOURS	168	Session lifetime in hours; 1–2,160
GEARBEACON_ALLOWED_ORIGINS	same origin	Extra browser origins
GEARBEACON_COOKIE_SECURE	URL detection	Force Secure cookies

Storage and retention

Variable	Default	Purpose
GEARBEACON_DATA_DIR	OS data folder	Persistent data override
GEARBEACON_BACKUP_INTERVAL_HOURS	24	0 disables scheduled backups
GEARBEACON_BACKUP_RETENTION	10	Database backups to retain
GEARBEACON_HISTORY_RETENTION_DAYS	365	Product changes, inventory insight intervals, and monitoring coverage retention
GEARBEACON_EVENT_RETENTION_DAYS	365	Activity retention; 0 keeps activity indefinitely
GEARBEACON_SECONDARY_BACKUP_DIR	blank	Absolute recovery directory or mounted share
GEARBEACON_SECONDARY_ENCRYPTED_EXPORTS	0	Encrypt secondary copies; save its passphrase in Settings first

Delivery and operational alerts

Variable	Default	Purpose
GEARBEACON_NOTIFICATION_MAX_ATTEMPTS	5	Delivery attempt limit
GEARBEACON_NOTIFICATION_GROUP_SECONDS	0	Optional event grouping window
GEARBEACON_NOTIFICATION_COOLDOWN_MINUTES	30	Suppress duplicate product/event alerts during this window
GEARBEACON_TIME_ZONE	system timezone	IANA timezone for schedules
GEARBEACON_QUIET_HOURS_ENABLED	0	Hold normal alerts during quiet hours
GEARBEACON_QUIET_HOURS_START / GEARBEACON_QUIET_HOURS_END	22:00 / 07:00	Local quiet-hours window
GEARBEACON_DIGEST_ENABLED / GEARBEACON_DIGEST_TIME	0 / 09:00	Enable and schedule a daily digest
GEARBEACON_ALERT_MONITOR_FAILURES	1	Alert after repeated store-check failures
GEARBEACON_ALERT_NOTIFICATION_FAILURES	1	Alert when a channel exhausts delivery attempts
GEARBEACON_ALERT_BACKUP_FAILURES	1	Alert when a scheduled backup fails
GEARBEACON_ALERT_LOW_DISK	1	Alert when less than 1 GB remains

Notification integrations

Variable	Default	Purpose
NTFY_BASE_URL / NTFY_TOPIC / NTFY_TOKEN	https://ntfy.sh / blank / blank	ntfy integration
DISCORD_WEBHOOK_URL	blank	Discord webhook
GOTIFY_BASE_URL / GOTIFY_TOKEN	blank	Gotify integration
GEARBEACON_WEBHOOK_URL	blank	Generic webhook
GEARBEACON_WEBHOOK_TOKEN	blank	Optional bearer token
GEARBEACON_WEBHOOK_HMAC_SECRET	blank	Optional signing secret
SMTP_HOST / SMTP_PORT	blank / 587	SMTP server
SMTP_SECURE	port-based	Implicit TLS
SMTP_STARTTLS	1	Require STARTTLS when not using implicit TLS
SMTP_REJECT_UNAUTHORIZED	1	Validate SMTP certificate
SMTP_USER / SMTP_PASSWORD	blank	SMTP credentials
SMTP_FROM / SMTP_TO	blank	Sender and recipients

Email appearance

Variable	Default	Purpose
GEARBEACON_EMAIL_DETAIL_LEVEL	standard	compact, standard, or detailed email layout
GEARBEACON_EMAIL_EMBED_IMAGES	1	Embed allowlisted product images as inline attachments
GEARBEACON_EMAIL_EXPLAIN_REASON	1	Include why each alert was sent
GEARBEACON_EMAIL_PRICE_CALCULATIONS	1	Show savings or price-increase math
GEARBEACON_EMAIL_DIGEST_MAX_ITEMS	12	Maximum unique products shown per digest, 1–50
GEARBEACON_EMAIL_SUBJECT_PREFIX	[GearBeacon]	Optional subject prefix, up to 60 characters
GEARBEACON_EMAIL_THEME	auto	auto, light, or dark email colors

Updates and build information

Variable	Default	Purpose
GEARBEACON_BUILD_COMMIT / GEARBEACON_IMAGE	blank	Build provenance shown in Operations
GEARBEACON_GITHUB_RELEASE_API	project releases	Manual update source; blank disables
GEARBEACON_UPDATE_MANIFEST_URL	blank	Custom update channel

Limits and deployment differences

Setting	Accepted range / behavior
Polling	Minimum 30 seconds
Stale threshold	At startup, at least three poll intervals; default floor 180 seconds
Catalog size ratio	0.10–0.95; default 0.55; one part of catalog validation, not a stock threshold
Primary backup retention	1–100 backups
Backup interval	Hours; 0 disables scheduled backups
Product/insight history	30–3,650 days; inventory/coverage record caps also apply
Activity retention	0–3,650 days; 0 retains activity indefinitely
Delivery attempts	1–10
Grouping window	0–3,600 seconds
Notification cooldown	0–10,080 minutes
Email digest items	1–50 unique products
Email subject prefix	At most 60 characters; no line breaks
Secondary export passphrase	At least 12 characters; save through Settings > Data before enabling encrypted copies

The provided Compose file uses private mode, an internal 0.0.0.0 bind, /data, and UTC scheduling by default. Host exposure is controlled separately by ports. It also supports GEARBEACON_IMAGE_TAG for selecting the image; this is a Compose interpolation value, not an application setting.

GEARBEACON_COOKIE_SECURE=1 requires clients to use HTTPS for authenticated sessions. An HTTPS public URL also enables secure cookies. A public URL does not set up TLS, DNS, routing, or a reverse proxy by itself.

GEARBEACON_OWNER_PASSWORD_FILE, GEARBEACON_OWNER_PASSWORD, and the reset flag are bootstrap/recovery controls. Remove reset/password overrides after recovery to avoid repeatedly resetting credentials. See Security and access.

GEARBEACON_GITHUB_RELEASE_API defaults to the project's latest-release API; an explicitly blank value disables that source. A custom manifest is an owner-selected update source. Neither option authorizes unattended installation. Build commit/image values describe provenance shown in Operations; they do not change application behavior or version.

Test-fixture flags and internal legacy-migration escape hatches are intentionally outside the owner configuration table. Development tests define those fixtures; do not use them to bypass authentication or catalog safety.

Related: Notifications, Email and webhooks, Backups, server implementation, Compose mapping.