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
Section titled “Bundle contents”docker-compose.selfhosted.yml # the stack definition.env.selfhosted.example # config templatelicense-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 guideimages/ # GridNMS container images (loaded by install.sh)Unpack it into a working directory, e.g. /opt/gridnms.
Configure .env
Section titled “Configure .env”cp .env.selfhosted.example .envEdit .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
Section titled “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 |
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
Section titled “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 |
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).
Require verified collector identity
Section titled “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 -dThis 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.
Changing a host port
Section titled “Changing a host port”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:
docker compose -f docker-compose.selfhosted.yml up -dThree things to know before you move a port:
- If you change
HTTPS_PORT, changeAPP_URLto match — including the port, for examplehttps://gridnms.yourco.internal:8443. The two have to agree or sign-in is refused (see the caution above). - Moving
HTTP_REDIRECT_PORTturns 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 onhttp://. - 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.
Enrolling the bundled collector
Section titled “Enrolling the bundled collector”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:
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.
Install
Section titled “Install”./install.shThe 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 -dWhen 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