Source Installation

Source installations require Node.js 22.13 or newer. The compiled application is committed in backend/dist and uses Node's built-in SQLite, so simply running a checkout does not require npm install. Development and rebuilding TypeScript use separate development commands.

Get the source

Use a published source archive for a fixed release, or clone the stable branch:

git clone --branch main https://github.com/alexphillips-dev/GearBeacon.git
cd GearBeacon
node --version

main contains reviewed stable changes; dev is ongoing development. A checkout of main may include documentation or layout changes made after an existing release archive was created.

Layout compatibility: the current checkout stores source launchers in launchers/. The published v1.2.0 source ZIP predates that move and keeps run-windows.bat, run-mac-linux.sh, and their private/mock equivalents at its root. In that archive, omit launchers/ from the commands below. Keep the archive's original directory structure intact.

Local-only launch

From the current checkout root, on Windows:

.\launchers\run-windows.bat

On macOS/Linux:

chmod +x launchers/run-mac-linux.sh
./launchers/run-mac-linux.sh

Open http://localhost:8787. On Windows you can also open the batch file directly. The launchers resolve the application directory themselves; live data is stored outside the checkout in the platform data directory.

Private server launch

Use launchers/run-private-windows.bat or ./launchers/run-private-mac-linux.sh. These launch in authenticated private mode and initially bind 0.0.0.0. Read the printed one-time setup token and finish owner setup. Restrict access to your intended LAN/VPN, or configure HTTPS.

Offline demo

Use launchers/run-mock-windows.bat or ./launchers/run-mock-mac-linux.sh for a local mock catalog. Mock mode uses a separate gearbeacon.mock.sqlite3 database. For an isolated development/demo environment, also set GEARBEACON_DATA_DIR to a dedicated temporary directory before launching so the entire demo installation is separate from normal data.

Use mock credentials and channels for testing; a mock catalog is not permission to point test processes at the owner's installation. Mock controls are for fixtures and demonstrations, not real stock information.

Explicit environment configuration

GearBeacon's ordinary Node command and launchers do not automatically load .env. Browser-saved settings are the usual configuration mechanism. For an initial scripted setup, copy .env.example to a private, ignored .env, edit it, and explicitly load it from the repository root:

node --env-file=.env --no-warnings backend/dist/index.js

Do not commit the file or put real passwords/tokens in shared examples. Exported shell environment variables take precedence over the file in Node, and GearBeacon's persisted application settings subsequently take precedence over environment defaults for settings it saves. Node documents its environment-file behavior.

The convenience launchers choose their named access mode/bind values. Use the direct command for a custom process environment, and check Settings > General for settings already persisted by the app. Listener and region changes require a restart.

Stop, update, or run continuously

Use Ctrl+C to stop a foreground instance. Monitor continuously only while the host is awake and the process is running. For automatic startup, standalone service packages or Docker provide the documented deployment paths; standalone installer scripts expect an extracted standalone executable package.

Follow Updates and rollback to back up first, replace source files or fast-forward your checkout, restart, and refresh the browser. Do not run two instances against one data directory.