Installation guide

From an empty Docker host to a working NMS.

Every command is explicit and inspectable. Server, TLS, firewall, agent, collector, Monit, backup and upgrade procedures are all here.

Docker ComposeGit cloneNo install scriptNo prebuilt server image

Before you begin

Requirements and decisions

Use a Linux host with a current Docker Engine, Docker Compose plugin, Git and enough persistent storage for your retention period. Choose a DNS name such as nms.example.com, then decide whether Caddy owns public ports 80/443, coexists with Apache or Nginx, or uses a private CA.

confirm tools
git --version
docker --version
docker compose version
openssl version
Your data stays on your host: PostgreSQL, metrics, logs, certificates and backups use named Docker volumes. Plan off-host copies of encrypted backups.

Server installation

Clone and prepare the source

01

Clone

shell
sudo mkdir -p /opt/golive-nms
sudo chown "$USER":"$USER" /opt/golive-nms
git clone https://github.com/TerminalAddict/golive-nms.git /opt/golive-nms
cd /opt/golive-nms
02

Create private configuration

shell
cp .env.example .env
chmod 600 .env
nano .env
03

Select exactly one TLS override

Use the tabs below, then copy the matching supplied file to compose.override.yml.

04

Inspect before running

shell
docker compose config
docker compose config -q
No opaque installer: GoLive uses ordinary Git, editor and Compose commands. The application and backup images build locally from source.

HTTPS

Choose a TLS layout

Caddy owns public 80 and 443

.env and shell
GOLIVE_DOMAIN=nms.example.com
GOLIVE_WEB_PORT=443
cp deploy/compose.direct.yml compose.override.yml

Public DNS must point to this host. Ensure no other process owns ports 80 or 443.

Secrets and settings

Configure .env

Replace every change-me value with an independent secret.

minimum .env
GOLIVE_DOMAIN=nms.example.com
GOLIVE_WEB_PORT=443
GOLIVE_COLLECTOR_PORT=9443
POSTGRES_PASSWORD=use-a-long-random-password
GOLIVE_ENCRYPTION_KEY=use-an-independent-random-32-byte-value
GOLIVE_ADMIN_EMAIL=admin@example.com
GOLIVE_ADMIN_PASSWORD=use-a-different-long-password
GOLIVE_AGENT_TOKEN=use-a-long-random-emergency-token
GOLIVE_MONIT_USERNAME=monit
GOLIVE_MONIT_PASSWORD=use-a-long-random-monit-password
GOLIVE_BACKUP_PASSPHRASE=use-a-long-random-backup-passphrase
GOLIVE_SYSLOG_PORT=5514
GOLIVE_TRAP_PORT=1162
GOLIVE_BACKUP_INTERVAL=24h
GOLIVE_BACKUP_KEEP=10
GOLIVE_RETENTION_DAYS=395
generate secrets
openssl rand -hex 24
openssl rand -base64 32
Back up both: the encryption key unlocks stored credentials and the internal CA; the backup passphrase decrypts archives. Losing either is not recoverable.

Optional OIDC SSO

.env
GOLIVE_OIDC_ISSUER=https://identity.example.com
GOLIVE_OIDC_CLIENT_ID=golive-nms
GOLIVE_OIDC_CLIENT_SECRET=replace-with-client-secret
GOLIVE_OIDC_REDIRECT_URL=https://nms.example.com/api/v1/auth/oidc/callback

Server network access

Open only what you use

PurposePortRequired
UI and enrollment443 or 8443 TCP/HTTPSYes
Public ACME80 TCPPublic TLS
Agents, collectors, Monit9443 TCP/HTTPSWhen used
Syslog5514 TCP/UDPOptional
SNMP traps1162 UDPOptional
UFW
sudo ufw allow 8443/tcp comment 'GoLive web and enrollment'
sudo ufw allow 9443/tcp comment 'GoLive agents collectors and Monit'
# Optional receivers
sudo ufw allow 5514/tcp
sudo ufw allow 5514/udp
sudo ufw allow 1162/udp
firewalld
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --permanent --add-port=9443/tcp
sudo firewall-cmd --reload
Prefer source restrictions. Never expose PostgreSQL 5432, VictoriaMetrics 8428, VictoriaLogs 9428 or internal app port 8080.

First start

Build and verify

shell
cd /opt/golive-nms
docker compose config -q
docker compose up -d --build --wait
docker compose ps

Inspect failures with:

shell
docker compose logs --tail=200 app
docker compose logs --tail=200 caddy
docker compose logs --tail=200 postgres

Deliberately reset a failed first install

Destructive: removes this project's database, metrics, logs, certificates and backups.
shell
docker compose down -v --remove-orphans
docker compose config
docker compose up -d --build --wait

First login

Establish your operating model

Open the configured HTTPS URL and sign in with GOLIVE_ADMIN_EMAIL and GOLIVE_ADMIN_PASSWORD.

  1. Create sites and locations.
  2. Create managers, site managers and viewers; assign site grants.
  3. Add encrypted SNMP, RouterOS, SSH or Monit credentials.
  4. Create email, Slack and Teams alert channels.
  5. Send a test through every channel.
  6. Add devices, parent relationships and checks.
  7. Create maintenance windows for scheduled outages.
Remember me: the 30-day option creates a secure persistent session. The browser password manager stores passwords; GoLive does not place them in browser storage.

Remote Linux hosts

Install the static Linux agent

No runtime dependencies and no inbound agent port. In Settings → Agents and collectors, choose Linux agent, select its site and generate a one-use, 15-minute enrollment token.

Two URLs: enrollment uses the management URL; ongoing mTLS reporting uses port 9443. The private key is generated locally.
Debian / Ubuntu
uname -m
wget https://github.com/TerminalAddict/golive-nms/releases/download/VERSION/golive-agent_VERSION_linux_amd64.deb
sudo dpkg -i ./golive-agent_VERSION_linux_amd64.deb
sudoedit /etc/golive-agent.env
/etc/golive-agent.env
GOLIVE_SERVER=https://nms.example.com:9443
GOLIVE_ENROLL_URL=https://nms.example.com
GOLIVE_ENROLLMENT_TOKEN=PASTE_THE_ONE_TIME_TOKEN
systemd
sudo systemctl daemon-reload
sudo systemctl enable --now golive-agent
sudo journalctl -u golive-agent -f
OpenRC
sudo rc-update add golive-agent default
sudo rc-service golive-agent start
tail -f /var/log/golive-agent.log

After enrollment, remove the enrollment URL and token, leaving only GOLIVE_SERVER, then restart.

Remote sites

Install a site collector

A collector connects outbound to GoLive and polls its site's private targets. It opens no inbound port.

  1. Choose Remote site collector in Settings.
  2. Assign the site and generate a token.
  3. Install the matching golive-collector package or tarball.
  4. Configure server, enrollment URL and token as above.
  5. Start it, check its journal, then remove enrollment values.
collector host
sudoedit /etc/golive-collector.env
sudo systemctl enable --now golive-collector
sudo journalctl -u golive-collector -f

Central polling automatically resumes if the collector is unavailable or revoked.

Monit integration

Send all Monit services to GoLive

monitrc
set eventqueue
    basedir /var/lib/monit/events
    slots 1000
set mmonit https://monit:YOUR_MONIT_PASSWORD@nms.example.com:9443/collector
    with timeout 15 seconds
    and register without credentials
validate
sudo monit -t
sudo monit reload
sudo monit status

Optional remote actions

monitrc
set httpd port 2812 and
    allow golive:LONG_UNIQUE_PASSWORD
    allow localhost
restrict on Monit host
sudo ufw allow proto tcp from 203.0.113.10 to any port 2812   comment 'GoLive Monit control'
sudo monit -t
sudo systemctl reload monit
Never expose 2812 publicly. Use a private network/VPN, or HTTPS with a certificate GoLive trusts.
  1. Create a Monit remote-control credential in Settings → Network credentials.
  2. Open the device and enter http://host:2812.
  3. Select the credential, save, then use Test & sync services.
  4. Use audited start, stop, restart, monitor and unmonitor controls.

Complete firewall matrix

Every communication

Source → destinationPortPurpose
Browser → NMSWeb HTTPSUI, API, enrollment
Agent / collector → NMSWeb HTTPSOne-time CSR
Agent / collector / Monit → NMS9443 TCPReports and assignments
NMS → Monit2812 TCPOptional actions
Devices → NMS5514 TCP/UDP; 1162 UDPSyslog and traps
NMS / collector → targetsICMP / configured TCPChecks
NMS / collector → SNMP161 UDPPolling
NMS / collector → MikroTik8728 / 8729 TCPRouterOS
NMS → managed device22 TCPConfig capture
NMS → SMTP25 / 465 / 587 TCPEmail
NMS → webhooks / OIDC443 TCPAlerts and SSO
Hosts → DNS / NTP53 / 123Names and time

Agents and collectors do not listen for NMS connections. A site collector—not the central server—needs access to that site's targets.

Protect your history

Back up and restore

backup now
cd /opt/golive-nms
docker compose run --rm backup backup
restore
docker compose stop app victoriametrics victorialogs
docker compose run --rm backup restore /backups/golive-YYYYMMDDTHHMMSSZ.tar.age
docker compose up -d --wait
Copy encrypted archives off-host and test restoration periodically.

Safe maintenance

Upgrade only this project

NMS server
cd /opt/golive-nms
docker compose run --rm backup backup
git pull --ff-only
docker compose up -d --build --wait
docker image prune
docker compose ps

Never stop every container on a shared host. Migrations run at startup. Agent package upgrades retain state and do not require reenrollment.

Diagnostics

Troubleshooting checklist

  1. Check DNS from the affected host.
  2. Synchronize clocks.
  3. Distinguish enrollment web port from collector port 9443.
  4. Use an unused token under 15 minutes old.
  5. Confirm certificate trust.
  6. Inspect Compose service status and logs.
  7. Inspect agent or collector journals.
  8. Check NAT and both firewalls.
  9. Confirm the identity is not revoked.
  10. Test direct target reachability from the polling host.
reachability
getent hosts nms.example.com
curl -v https://nms.example.com/
openssl s_client -connect nms.example.com:9443   -servername nms.example.com </dev/null
Open an issueRepository guide