HTTPS / TLS

Self-hosted GridNMS serves HTTPS by default. On first start it generates a self-signed certificate automatically, so the UI is encrypted out of the box — nothing to configure. When you’re ready, swap in your own certificate or have GridNMS get a free one from Let’s Encrypt.

What you get by default

• The web UI and API are served over HTTPS on port 443.
• Port 80 redirects to HTTPS (and answers Let’s Encrypt challenges if you enable that — see below).
• A self-signed certificate is generated on first boot and reused after that.

Self-signed = a one-time browser warning

Because the default certificate is self-signed, your browser shows a “not private / not trusted” warning the first time. That’s expected — the connection is still encrypted. Click through it (Advanced → Proceed), or switch to a trusted certificate using one of the options below.

Everything inside the stack is encrypted too

The certificate above is what browsers see. Internally, GridNMS also encrypts every link inside the stack so nothing travels in plaintext — even between containers on the same host. At install time an instance certificate authority is generated and used to secure:

• the collector → server control channel (wss) and collector → log-service channel (https);
• the server → PostgreSQL (TLS), server → Memgraph (bolt+TLS), and log-service → ClickHouse (https) connections.

This is automatic — there’s nothing to configure. Everything trusts the instance CA, which you can download below to trust on your own devices or remote collectors.

Manage certificates from the UI

The easiest way to manage your certificate is in the app: go to Configure → TLS Certificate (admin only). From there you can see the current certificate and change it — and every change is applied live, with no restart.

The page has four parts:

• Current certificate — the active mode (Self-signed / Your certificate / Let’s Encrypt), the common name and issuer, the subject alternative names, the access URL, and the expiry with a days-remaining badge (green → amber → red as it approaches). A Download instance CA button appears on self-signed deployments so you can trust the CA on your browsers and remote collectors.
• Upload your own certificate — paste a PEM certificate (full chain) and its private key, then Upload & apply. GridNMS validates that the key matches the certificate before applying; an invalid pair is rejected with a clear message.
• Let’s Encrypt (public domain) — enter a domain and contact email and Request certificate. GridNMS obtains and auto-renews it (a staging toggle is available for testing). Requires a public domain reachable on ports 80 + 443.
• Self-signed (default) — Regenerate the built-in certificate, e.g. after changing the access URL. No external dependencies.

Self-hosted only

This page only appears on self-hosted instances. Cloud (SaaS) terminates TLS at the edge, so there’s nothing to manage there.

Everything below can also be done from the command line / .env if you prefer.

Option 1 — Bring your own certificate

If you already have a certificate (from your own CA, or a commercial one):

1. Put the two files in a certs folder next to your docker-compose.selfhosted.yml:
   • certs/cert.pem — the full certificate chain
   • certs/key.pem — the private key
2. Restart the stack:

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

GridNMS detects the files and uses them automatically — no other config needed. To rotate later, replace the files and restart.

Option 2 — Automatic Let’s Encrypt (public domain)

If your instance has a public DNS name and is reachable from the internet on ports 80 and 443, GridNMS can obtain and auto-renew a free, trusted certificate for you:

1. Point a DNS record (e.g. gridnms.example.com) at the host.
2. In your .env, set:

   APP_URL=https://gridnms.example.com
   GRIDNMS_TLS_DOMAIN=gridnms.example.com
   GRIDNMS_TLS_ACME_EMAIL=ops@example.com

3. Restart the stack.

GridNMS requests the certificate over the standard HTTP-01 challenge (port 80), installs it, and renews it automatically before it expires. If issuance ever fails (DNS not ready, port 80 blocked), GridNMS falls back to the self-signed certificate so the UI stays reachable — fix the cause and restart to retry.

Note

Let’s Encrypt requires a real, publicly-resolvable domain and inbound 80/443. On a private LAN with no public domain, use Option 1 (your own cert) or the default self-signed certificate.

Make sure your access URL matches

APP_URL is also the passkey (WebAuthn) origin, so it must match exactly how you reach the UI — including https://. The installer sets this to an https:// URL by default. If you change how the instance is reached, update APP_URL in .env and restart, or passkey sign-in will fail with an origin mismatch (password sign-in still works). See Configuration.

Turning HTTPS off

Behind your own load balancer or reverse proxy that already terminates TLS? You can serve plain HTTP instead:

GRIDNMS_TLS_ENABLED=false

The server then serves HTTP on APP_PORT (default 3001) only. Set APP_URL to the https:// address your proxy presents so cookies and passkeys still behave.

Ports reference

Port	Purpose
443	HTTPS — the browser-facing UI + API (default)
80	Redirects to HTTPS; serves Let’s Encrypt challenges
3001	Plain HTTP — internal use (collector, health checks) and optional LAN fallback

Renewal

You don’t need to do anything — GridNMS checks daily and renews automatically: the Let’s Encrypt certificate before expiry, and the self-signed certificate when it nears its end of life. A renewed certificate is swapped in without dropping connections.

Related

• Configuration — .env settings, including APP_URL.
• First Run — completing setup after install.
• Troubleshooting — login, passkey, and access issues.