Skip to main content

Configuration

GEM's server configuration lives in gem.json at the install root, loaded at startup. The standard installer writes a working gem.json for you; this page explains the settings you're most likely to change.

:::info Where settings live gem.json holds server bootstrap settings — how to reach the database, which ports to bind, whether HTTPS and the remote tunnel are on. Everything else (devices, zones, users, macros, attributes) is stored in the database and configured through the admin interface, not this file. :::

Database connection​

{
  "data": {
    "connection": {
      "host": "localhost",
      "port": 5432,
      "user": "gem_user",
      "password": "gempass",
      "database": "gem_db"
    },
    "sequelize": {
      "dialect": "postgres",
      "schema": "gem",
      "timezone": "America/Chicago"
    }
  }
}
  • connection — how GEM reaches PostgreSQL. The installer creates this database and user; change these values only if you point GEM at a different database.
  • sequelize.schema — GEM keeps all of its tables in the gem schema.
  • sequelize.timezone — set this to the site's local timezone so schedules and history line up with wall-clock time.

Ports and HTTPS​

{
  "port": 3000,
  "ssl": {
    "enabled": false,
    "port": 8443,
    "http_port": 8080,
    "auto_regenerate": true
  }
}
  • port — the HTTP port GEM serves on (default 3000).
  • ssl.enabled — turn on HTTPS. When enabled, GEM serves HTTPS on ssl.port and HTTP on ssl.http_port.

Remote access (tunnel)​

{
  "tunnel": { "enabled": true },
  "external_url": "https://your-site.example.com"
}

When the tunnel is enabled, GEM establishes a secure outbound connection for remote access — no inbound firewall ports need to be opened.

You can also turn the tunnel on or off at runtime — without editing gem.json or restarting — by setting a tunnel system attribute (a JSON value such as {"enabled": true} or {"enabled": false}) from the admin System Attributes grid. The attribute overrides the gem.json value and replaces the whole tunnel object, so include every field you need. Live connection status is shown by the Orchestrator Tunnel dashboard widget.

Notifications​

gem.json carries the transport settings for outbound email (mail) and SMS (sms) used by alerts and notification profiles. Configure the recipients and rules themselves in the admin interface under notification profiles.

Updates​

{
  "update_url": "https://updates.mygem.us",
  "update_key": "<your-key>"
}

These control where GEM pulls updates from. The installer sets them; you normally won't touch them.

The Encryption Key (.encryption_key)​

GEM encrypts secure attributes (passwords, API keys, private keys) at rest using a key stored in a file named .encryption_key at the install root. It is generated automatically the first time the server starts.

:::danger Back up .encryption_key — losing it is unrecoverable This file is the key to every encrypted attribute in your database. If you lose it, those values cannot be decrypted and must be re-entered by hand.

  • Back it up somewhere secure, separately from the database.
  • Never commit it to source control (it is git-ignored by default).
  • When migrating a system to new hardware, copy .encryption_key along with the database. :::

GEM exposes secure download/upload of the encryption keys from the admin interface for backup and migration. See Concepts → Secure Attributes.