Configuration

The setup email links to the self-hosted bundle, published as both gridnms-selfhosted-bundle.tar.gz (Linux/macOS) and gridnms-selfhosted-bundle.zip (Windows).

Bundle contents

docker-compose.selfhosted.yml   # the stack definition
.env.selfhosted.example         # config template
license-public.pem              # GridNMS license verify key (public, ships with the bundle)
install.sh                      # one-command installer (Linux/macOS)
install.ps1                     # one-command installer (Windows / PowerShell)
SETUP.md                        # setup guide
images/                         # GridNMS container images (loaded by install.sh)

Unpack it into a working directory, e.g. /opt/gridnms.

Configure .env

cp .env.selfhosted.example .env

Edit .env and set the required values. The stack refuses to start until these are filled — there are intentionally no defaults for secrets:

Variable	What to set
GRIDNMS_DBPASSWD	A strong database password
GRIDNMS_SECRET	A strong session secret — openssl rand -hex 32
GRIDNMS_LICENSE_KEY	The license key from your approval email

If you run ./install.sh (recommended — see Install below), it generates all of the above for you except the license key, which it prompts for. The table is here for the manual path and for reference.

Generated for you — back these up

Five more variables are required, but you don’t set them by hand: ./install.sh generates them into .env on first run.

Variable	What it’s for
GRIDNMS_MASTER_KEY	Encrypts device credentials (SNMP communities, SSH passwords, etc.) at rest
GRIDNMS_GRAPH_PASSWORD	Auth for the internal topology store
GRIDNMS_OPAMP_SERVICE_TOKEN	Auth between the server and the bundled collector control service
CLICKHOUSE_PASSWORD	Auth for the bundled log store
LOGSERVER_TOKEN	Auth between the server and the bundled log service

Back up GRIDNMS_MASTER_KEY off-box

GRIDNMS_MASTER_KEY is the root of trust for every encrypted credential in your instance. install.sh prints it once when it’s generated — copy it into a password manager or secrets vault immediately. If it’s lost, encrypted data (your saved device credentials) is permanently unrecoverable — not by GridNMS support, not by re-running the installer. A backup of the host disk alone isn’t enough if that backup lives next to the only copy of the key.

The platform connection is preconfigured — you don’t need to set anything for it. It’s how your instance checks its license and receives collector/pack updates.

license-public.pem ships with the bundle and is the same for every customer — leave it next to the compose file. It is a public, verify-only key; it can never mint or grant a license, only check the signature on the one the platform issues to you.

Optional knobs

Variable	Purpose
APP_URL / APP_PORT	Where the UI is reached — also the WebAuthn / passkey origin
GRIDNMS_TLS_DOMAIN, GRIDNMS_TLS_ACME_EMAIL	Auto-issue a Let’s Encrypt cert for a public domain. HTTPS is on by default (self-signed) — see HTTPS / TLS
GRIDNMS_TLS_ENABLED=false	Disable HTTPS (serve plain HTTP on APP_PORT) — for use behind your own TLS proxy
GRIDNMS_DIAGNOSTICS_OPT_IN=1	Share anonymous diagnostics
UPDATER_AUTO_APPLY=1	Let the updater apply server updates unattended (default: notify-only) — see Updates
GRIDNMS_LOGHOUSE_ARM_COLLECTOR_IDENTITY=true	Require every collector to prove its identity before its logs, metrics, and discovery results are accepted — see below

Set APP_URL correctly

APP_URL is the WebAuthn / passkey origin — it must match the URL you actually type in the browser, or passkey enrollment fails with an origin mismatch (password login still works). If you front the instance with a DNS name or reverse proxy, set that URL.

Require verified collector identity

Every collector’s logs, metrics, and discovery results normally carry a signed identity your instance issued when it joined — this is already checked in the background, so you don’t need to do anything for it to work. Setting GRIDNMS_LOGHOUSE_ARM_COLLECTOR_IDENTITY=true goes a step further: it makes your instance reject anything on those channels that doesn’t carry a valid, current identity — for example, from a collector you’ve revoked.

This is off by default. Before turning it on, give your instance a few minutes after every collector has connected at least once, then check Configure → Collectors — every collector you expect to see should show Online. If one doesn’t, its logs and metrics will stop being accepted once you enable this, so reconnect it first.

Restart the stack after changing it:

docker compose -f docker-compose.selfhosted.yml up -d

This setting never affects the app itself, your device inventory, or anything already stored — it only changes whether new log/metric/discovery data from an unverified sender is accepted going forward.

Install

./install.sh

The installer generates your secrets, asks for your license key, and prompts for the URL users will reach the instance at (defaulting to the host’s primary IP). It then brings the stack up and waits for health. The equivalent manual command (images must already be loaded — install.sh does that):

docker compose -f docker-compose.selfhosted.yml up -d

When healthy (<host> = the APP_URL you set):

Web app:  https://<host>            (HTTPS by default; the UI and API share the server)
Health:   https://<host>/health →  {"status":"ok"}

Open the UI and complete the first-run setup wizard.