Install the ZenPlus appliance

01 At a glance #

ZenPlus ships as a self-contained appliance. There is no cluster to design, no package matrix to resolve and no follow-up configuration script — the installer provisions every component, verifies that it actually came up, and prints exactly what to do next.

02 Requirements #

A dedicated virtual machine or physical server is recommended. The appliance runs its own PostgreSQL, Redis and ClickHouse instances, so a host that already runs those services will need manual cleanup first.

2.1 · Outbound network access

Installation requires outbound HTTPS. The installer checks reachability before it writes anything and stops with a clear message if any host is unreachable — so a firewall problem costs you seconds, not ten minutes of a failed build.

2.2 · Inbound (LAN) ports

No inbound port from the public internet is required. Registration and OTA updates are outbound-only.

2.3 · The preflight gate

The first step rejects unsuitable hosts in seconds rather than failing halfway through a build. It checks:

• OS family and release — Ubuntu 20.04 or newer; anything else is a hard stop, Debian raises an "untested" warning.
• CPU architecture — must be amd64 / x86_64.
• Memory and free disk — against the minimums above, on the filesystem that will hold /opt/zenplus.
• Port conflicts — ports 80, 8000, 5432, 6379, 8123 and 9000 are inspected; unknown listeners raise a warning, ZenPlus's own services do not.
• Outbound HTTPS — a live reachability probe of every download host.

03 Run the installer #

On a fresh Ubuntu server, as root or with sudo:

curl -fsSL https://zentryc.com/install.sh | sudo bash

Equivalent, straight from the source repository:

curl -fsSL https://raw.githubusercontent.com/khuram2025/zen-mon/main/install.sh | sudo bash

Installation takes 8–15 minutes on a typical server — most of that is compiling the Go poller and building the React dashboard. Prefer to read before you run? Download first, inspect, then execute:

curl -fsSL https://zentryc.com/install.sh -o /tmp/zenplus-install.sh
less /tmp/zenplus-install.sh
sudo bash /tmp/zenplus-install.sh

3.1 · What you will see

The console stays a clean checklist. Every step reports one verified line, with the time it took:

  ╔══════════════════════════════════════════════════════════╗
  ║   ZenPlus — Network Monitoring Appliance                  ║
  ║   Automated Installer                                    ║
  ╚══════════════════════════════════════════════════════════╝

  Host      mon-01 (10.20.30.40)
  Source    zen-mon.git branch main
  Target    /opt/zenplus
  Log       /var/log/zenplus-install.log

  This takes 8–15 minutes on a fresh server. Safe to re-run.

  [01/16] Validating host                            ✓ (2s)
  [02/16] Installing system packages                 ✓ (3m14s)
  [03/16] Creating service account                   ✓ (0s)
  [04/16] Fetching application source                ✓ (18s)
  [05/16] Generating configuration                   ✓ (0s)
  [06/16] Building application                       ✓ (5m02s)
  [07/16] Initialising databases                     ✓ (1m11s)
  [08/16] Provisioning trial licence                 ✓ (0s)
  [09/16] Configuring services                       ✓ (12s)
  [10/16] Installing TLS/security tools              ✓ (1s)
  [11/16] Configuring OTA updater                    ✓ (3s)
  [12/16] Installing support tooling                 ✓ (2s)
  [13/16] Installing management CLI                  ✓ (0s)
  [14/16] Finalising installation                    ✓ (1s)
  [15/16] Verifying appliance health                 ✓ (14s)
  [16/16] Collecting system report                   ✓ (1s)

  Installation summary
  ──────────────────────────────────────────────────────────
   ✓  16 steps · 0 warnings · completed in 10m21s
  ──────────────────────────────────────────────────────────

  ✓ ZenPlus 1.11.0 is installed and running.

  Access
    Dashboard    http://10.20.30.40
    API docs     http://10.20.30.40/docs
    Sign in      admin / admin123   (change this immediately)

  Licence
    Trial active — expires 2026-09-10
    50 devices · 20 service checks · 5 users

Everything each step prints is captured in /var/log/zenplus-install.log, with ===== [n/16] Step title ===== markers. The console stays readable; the log holds the full detail.

3.2 · If a step fails

The installer stops at the first failure of a critical step, prints the last 25 lines of that step's output, and exits non-zero. Non-critical components — the TLS helper, OTA updater and support tooling — degrade to a warning and the install continues, leaving a working appliance with one feature to repair later.

Fix the reported cause and re-run the same command. The installer is idempotent: existing credentials, data directories, a changed admin password and any active subscription are all preserved.

04 The 16 steps, explained #

The steps run in a deliberate order — the application is built before the databases are initialised, because both the admin-hash repair and the trial seed need the Python virtual environment that the build step creates. Grouped by what they accomplish:

Solid chips are critical — a failure aborts the install. Dashed chips are non-critical: a failure warns and the install continues.

05 First login #

When the installer finishes it prints the access details for the appliance:

06 Trial licence and registration #

A 30-day trial is provisioned automatically during installation. There is no activation step, no sales call and no feature gate — the appliance is fully usable the moment it boots.

Every product capability is available during the trial — SNMP, NetFlow, NCM, APM, discovery, agents, sensors and reporting. Nothing is withheld. See pricing for the node bundles available after the trial.

6.1 · What a licence key unlocks

A licence key is required for exactly one thing: receiving over-the-air updates. Until the appliance is registered, update checks return an error and the Licenses tab shows "Appliance Not Registered". Monitoring is entirely unaffected.

Re-running the installer never resets, shortens or extends an existing subscription.

07 Enable HTTPS #

A fresh appliance serves plain HTTP. For anything beyond a lab, enable TLS before adding devices or agents — one action secures the dashboard, the API and all agent and sensor traffic at once.

Go to Settings → General → Security and pick the path that matches your environment:

Then enable HTTPS and, optionally, the HTTP→HTTPS redirect, HSTS, and a TLS 1.2+/1.3-only floor. See the Zentryc security model for how this fits the wider platform.

08 Verify the installation #

Step 15 already asserted appliance health before the installer exited. To re-check at any time:

sudo zenplus status

Every service below should report active:

zenplus-wait-deps
zenplus-api
zenplus-poller
zenplus-updater.timer
nginx
postgresql
redis-server

ClickHouse runs in Docker and should report healthy:

docker ps --filter name=zenplus-clickhouse

zenplus-clickhouse   Up 3 minutes (healthy)

A direct API health check bypasses nginx entirely:

curl -fsS http://127.0.0.1:8000/api/v1/system/health

{"status":"ok","service":"zenplus-api"}

And confirm the installed version — it must be a semantic version:

head -1 /opt/zenplus/.version

09 What gets installed #

Everything lands on one host. nginx is the only component listening to your network; the databases bind to loopback, the poller reaches out to your devices, and the updater reaches out to zentryc.com. Nothing calls in.

9.1 · Filesystem and services

9.2 · Privilege model

Nothing in ZenPlus runs as root beyond what the operating system itself requires:

• The API and poller run as the unprivileged zenplus system user.
• The poller sends ICMP echoes via the cap_net_raw file capability — a capability on the binary, not a root process.
• Dashboard-triggered update actions flow through a scoped sudoers file at /etc/sudoers.d/zenplus-updater that enumerates the exact systemctl invocations permitted — nothing else — plus a polkit rule for the equivalent D-Bus calls.
• Generated secrets live only in /opt/zenplus/.env at mode 0640; TLS private keys live in /etc/zenplus/tls at 0600, root-owned.

10 Managing the appliance #

The zenplus CLI is the day-to-day interface for anything that is not in the dashboard:

sudo zenplus status      # service and registration status
sudo zenplus update      # apply the latest release
sudo zenplus restart     # restart the application services
sudo zenplus start       # start everything, including databases
sudo zenplus stop        # stop the application services
sudo zenplus backup      # on-demand PostgreSQL dump
sudo zenplus logs api    # tail a log — api | poller | updater

10.1 · Files worth knowing

/var/log/zenplus-install.log          # complete installer output, per step
/opt/zenplus/.env                     # generated secrets and connection strings
/opt/zenplus/.version                 # semantic version + install timestamp
/opt/zenplus/updater/logs/update.log  # OTA agent activity
/etc/nginx/conf.d/zenplus.conf        # web server configuration

11 Staying up to date #

There are two update paths, and they lead to the same place.

12 Troubleshooting #

Where to look first: /var/log/zenplus-install.log holds the complete output of every step, delimited by ===== [n/16] Step title ===== markers. Then:

sudo zenplus status
sudo systemctl status zenplus-api --no-pager
sudo journalctl -u zenplus-api -n 120 --no-pager -l
sudo journalctl -u zenplus-poller -n 120 --no-pager -l
docker ps

sudo -u postgres psql -d zenplus -c \
"UPDATE users SET password_hash = '\$2b\$12\$vjHI8XBgL.dCyn.sgl41VufIFkQGcEzjt78GJdB66AwG9e9MZasai', is_active = true WHERE username = 'admin';"

sudo bash -lc 'set -e
export PATH=/usr/local/go/bin:/usr/local/bin:$PATH
git config --global --add safe.directory /opt/zenplus || true
mkdir -p /opt/zenplus/bin
cd /opt/zenplus/poller
go mod download
CGO_ENABLED=0 go build -buildvcs=false -o /opt/zenplus/bin/zenplus-poller ./cmd/poller
chown zenplus:zenplus /opt/zenplus/bin/zenplus-poller
chmod 0755 /opt/zenplus/bin/zenplus-poller
setcap cap_net_raw+ep /opt/zenplus/bin/zenplus-poller || true
systemctl restart zenplus-poller'

sudo bash /opt/zenplus/scripts/setup-security.sh
sudo systemctl restart zenplus-api

curl -fsS http://127.0.0.1:8000/api/v1/system/health
sudo systemctl status zenplus-wait-deps --no-pager
docker ps --filter name=zenplus-clickhouse
sudo journalctl -u zenplus-api -n 120 --no-pager -l

Still stuck? Contact Zentryc support and attach /var/log/zenplus-install.log — it contains everything the installer saw, step by step.

13 Advanced install options #

The installer reads a handful of environment variables, so you can change its behaviour without editing the script. Prefix them to the bash invocation:

curl -fsSL https://zentryc.com/install.sh | sudo ZENPLUS_BRANCH=release-1.11 bash

13.1 · Which version does a fresh install get?

install.sh clones the main branch and installs whatever version that branch carries. Cutting a release fast-forwards main to the released commit, so a fresh install always lands on the current release.

14 Publishing the installer Operators #

This section is for the team that runs zentryc.com, not for customers. The public one-liner is served as a static file and must not require login, API authentication or an access proxy.

In the server { server_name zentryc.com; … } block, before any generic application route:

location = /install.sh {
    root /var/www/zentryc-public;
    default_type text/plain;
    add_header Cache-Control "public, max-age=300";
    add_header X-Content-Type-Options "nosniff" always;
    try_files /install.sh =404;
}

Publish or refresh the file:

sudo mkdir -p /var/www/zentryc-public
sudo curl -fsSL https://raw.githubusercontent.com/khuram2025/zen-mon/main/install.sh \
  -o /var/www/zentryc-public/install.sh
sudo chmod 0644 /var/www/zentryc-public/install.sh
sudo nginx -t && sudo systemctl reload nginx

Verify from another machine:

curl -fsSIL https://zentryc.com/install.sh            # expect HTTP 200, text/plain
curl -fsSL  https://zentryc.com/install.sh | head -1  # expect #!/usr/bin/env bash

curl -fsSL https://zentryc.com/install.sh | grep ZENPLUS_BRANCH=

15 Related reading #

Change log for this guide