Skip to main content

Installation

Most sites install GEM with a single command. The installer provisions everything GEM needs — system dependencies, PostgreSQL, a bundled Node.js runtime, and a service to keep it running — and then hands off to a browser-based setup wizard that walks you through database, ports, and notifications.

If you're a developer working from the source tree instead, see Install from Source.

Linux​

Run the installer as root:

curl -fsSL https://updates.mygem.us/install.sh | sudo sh

That command is a small bootstrap: it downloads the versioned installer package, verifies its SHA-256 checksum, and runs it. From there you'll be prompted for an install directory and the system will be provisioned (see What the installer does below) before the setup wizard opens.

Windows (via WSL)​

GEM runs on Linux; on Windows it runs inside WSL. The Windows installer sets all of this up for you.

  1. Download and double-click the installer:

    https://updates.mygem.us/windows/install.bat

  2. When Windows SmartScreen appears, click More info → Run anyway.

  3. Approve the User Account Control (UAC) prompt.

The installer will enable WSL, install Ubuntu 24.04, configure mirrored networking (so GEM is reachable on your LAN at the Windows host's IP) with no idle suspend, reboot if Windows needs one to finish enabling WSL, and resume automatically after sign-in. It then runs the same Linux installer described here.

:::warning A reboot may happen mid-install Enabling WSL can require a restart. The installer is designed to pick up where it left off after you sign back in — let it finish before closing any windows it opens. :::

What the installer does​

Before the wizard opens, the installer prepares the machine:

  1. Asks for an install directory — default ~/Apps/GEM. If the directory already exists, it offers to overwrite and backs up any existing gem.json first.
  2. Installs system dependencies via apt — including PostgreSQL, ffmpeg, nmap, arp-scan, mDNS libraries, and build tools.
  3. Starts and enables PostgreSQL.
  4. Bundles its own Node.js runtime (the exact version GEM is built against) into <install-dir>/node/, verified against Node's official checksums. GEM always uses this bundled runtime, never a system Node.
  5. Installs GEM's dependencies, then launches the setup wizard.

:::info WSL without systemd On WSL, if systemd isn't active the service installation step is skipped (GEM still installs and runs). To enable it, add the following to /etc/wsl.conf and restart WSL:

[boot]
systemd=true

:::

The setup wizard​

The installer starts a local web server and opens a browser-based wizard to finish configuration. How you reach it depends on how you're installing:

  • On the machine directly (desktop session) — a browser opens automatically to the wizard.
  • Over SSH or headless — no browser is opened. The installer prints one or more URLs (on your LAN) to the terminal. Open one of them in a browser on another computer.

:::warning Use the exact URL the installer prints The wizard is protected by a one-time session token embedded in the printed URL (...?token=...). Open that URL as-is — a URL without the token is rejected. The token is unique to this install run. :::

The wizard walks you through, validating each step before moving on:

  1. Preflight checks — disk space, OS version, PostgreSQL presence, and whether a GEM service already exists.
  2. Database — connection settings; the wizard can create the PostgreSQL database, user, and schema for you and build the tables. (Configures pg_hba.conf for local password auth as needed.)
  3. Web port — the port GEM serves on (default 3000); checked to be free.
  4. Time zone — detected from the system and confirmed, so schedules and history use local time.
  5. Email (SMTP) — optional; for alerts and notifications. The wizard can send a test message.
  6. SMS (Twilio) — optional; the wizard can send a test text.
  7. AI key — optional Claude API key for AI features; validated with a live check.
  8. Service — installs GEM as a systemd service (gem) and starts it. Skipped if systemd isn't available.

Everything you enter is written to gem.json (see Configuration), with secrets stored with restricted permissions.

Verify the install​

When the wizard finishes, GEM is running as a service on the port you chose. Open a browser on the same network and navigate to:

http://<server-ip>:<port>

(<port> is 3000 unless you changed it; on Windows/WSL with mirrored networking, <server-ip> is the Windows host's LAN IP.) You should see the GEM login screen.

:::tip First login The system seeds a default administrator account on first boot. See First Boot for the credentials and the required password change. :::

What's next​

  • First Boot — log in and what happens on first start.
  • Quick Start — commission your first device end to end.
  • Configuration — everything the wizard wrote to gem.json, and how to change it later.

Updates​

GEM updates itself from updates.mygem.us — applied from within the running system, not by re-running the installer. Manage updates from the admin interface.