Skip to content

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).

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.

Terminal window
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.

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

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.

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
HTTPS_PORT Serve the UI on a different host port than 443 — see Changing a host port
HTTP_REDIRECT_PORT Host port for the HTTP redirect to HTTPS (default 80) — see Changing a host port
LOGSERVER_HOST_PORT The host port for the log service (default 3002). Change it only to run two instances on one host
GRID_TCP_PORT, GRID_TLS_PORT, GRID_METRICS_PORT Host ports for the bundled collector’s Log Forwarder channels (default 24742, 24743, 24744) — see Changing a host port
GRIDNMS_COLLECTOR_DISTRO_JOIN_TOKEN Enroll the bundled collector on start instead of by hand — see Enrolling the bundled collector

Collectors use the same address to fetch what they should poll, so it also has to be an https:// address. With a plain http:// address a collector still receives logs, answers ping checks and reports healthy, but it does not run SNMP polling or service checks, and the server logs a warning saying so each time it builds that collector’s configuration. The collector bundled with the install trusts the certificate the install created; a collector you run on another host needs that certificate’s authority installed on the host (certs/internal/ca.crt in the install folder).

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:

Terminal window
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.

Every port the stack publishes can be moved to a different host port if the default is already taken on your machine. The port inside the container is fixed, so only the host side changes and nothing else needs reconfiguring:

Setting Default What reaches it
HTTPS_PORT 443 Browsers, and collectors fetching what they should poll
HTTP_REDIRECT_PORT 80 Browsers arriving on http://, which are redirected to HTTPS
LOGSERVER_HOST_PORT 3002 The log service
GRID_TCP_PORT 24742 Log Forwarder data (plain)
GRID_TLS_PORT 24743 Log Forwarder data (encrypted)
GRID_METRICS_PORT 24744 Log Forwarder metrics

Set the ones you need in .env, then recreate the stack:

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

Three things to know before you move a port:

  • If you change HTTPS_PORT, change APP_URL to match — including the port, for example https://gridnms.yourco.internal:8443. The two have to agree or sign-in is refused (see the caution above).
  • Moving HTTP_REDIRECT_PORT turns off automatic Let’s Encrypt. The certificate is requested over a challenge that must answer on port 80 specifically, so if you move it, either keep something forwarding the real port 80 to it or supply your own certificate instead — see HTTPS / TLS. Moving it is otherwise safe: it only redirects browsers that arrive on http://.
  • The Log Forwarder management ports (4320 and 4321) are fixed. A forwarder derives the second from the first, so there is deliberately no setting for either. If a forwarder was installed against a non-default management port, publish that port and the one after it instead.

The collector that ships with the install starts unenrolled — it accepts nothing until you give it a join token. A fresh install has no account yet to mint one from, so this is always a step you take after the first-run setup.

Create the token from Configure → Collectors → Add Collector, then either paste it into .env as GRIDNMS_COLLECTOR_DISTRO_JOIN_TOKEN and bring the collector up:

Terminal window
docker compose -f docker-compose.selfhosted.yml up -d collector-distro

…or enroll it by hand with the exact commands install.sh prints when it finishes. The token is single-use either way.

Terminal window
./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):

Terminal window
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.

docs built 2026-11-12 · 945a2dec2