Skip to content

Suite architecture

NGX Ops is a suite of components organized around a classic Nginx. Only the Nginx + dashboard pair is required: all other components are optional, and each one can be used without the others.

The components

Component Role Where it runs
Nginx The reverse proxy, with its native configuration (conf.d, sites, snippets, streams) Main compose
Dashboard Interface, REST API, webhooks, control of Nginx and associated containers Main compose
Analyzer Analyzes access logs, raises alerts, feeds the blocklists. Written in Go Container created and managed by the dashboard
Emulated WAF Replays logs through a rule engine, never blocking directly Container managed by the dashboard
Challenge Browser challenge (proof of work) for flagged IPs Container managed by the dashboard
Shipper Sends logs to the log store Container managed by the dashboard
Agent Controls a remote Nginx or Docker server from the dashboard On each remote server
Hub Global, read-only view of several dashboards; receives their backups Dedicated compose
Log store Log database (PostgreSQL and TimescaleDB) with its API Dedicated compose
Intelligence Central SaaS service that receives alerts, computes a reputation per IP and publishes lists Hosted service
Redis Keeps in-progress statistics across restarts Main compose, redis profile

The analyzer, the emulated WAF and the shipper are three programs of the same image. The challenge, certbot, the GeoIP update, error pages and GoAccess are created on demand by the dashboard through the Docker socket: they do not appear in the compose file.

Overview

                        ┌──────────── main server ──────────────────┐
 visitors ──80/443──▶   │  Nginx ◀── configuration files            │
                        │    │            ▲                          │
                        │    │ logs       │ write, test, reload      │
                        │    ▼            │                          │
                        │  Analyzer ──▶ Dashboard ──Docker socket──▶ managed containers
                        │  Emulated WAF    │   ▲                     │
                        │  Challenge       │   │                     │
                        │  Shipper         │   │                     │
                        └──────────────────┼───┼─────────────────────┘
                                           │   │
        Agent (remote host) ──manifest────▶│   │◀── Hub (read-only, polls the dashboard)
                                           │
              Shipper ──gzip batches, write token──▶ Log store ◀── read token ── Dashboard, Hub
                                           │
                    Dashboard ──alerts (option)──▶ Intelligence

Who talks to whom

Flow Direction Authentication
Dashboard → Nginx Writes the configuration, runs nginx -t and reload, reads VTS statistics Docker socket, internal network
Dashboard → managed containers Create, stop, update image Docker socket
Dashboard ↔ analyzer, WAF, challenge Internal HTTP API Internal token managed by the dashboard
Shipper → Log store Compressed batches, replayable without duplicates write token, TLS
Dashboard and Hub → Log store Read, search, statistics read token
Producers (WAF, challenge) → Shipper Decisions sent over local HTTP Shared local token
Agent → Dashboard Periodic push of the remote host manifest Token specific to each agent, HTTPS
Hub → Dashboard The Hub polls the dashboard (pull); the reverse does not exist X-Hub-Token token; the dashboard only keeps its SHA-256 fingerprint
Dashboard → Hub Sends backups, only if this mode is enabled HUB_PUSH_TOKEN
Dashboard → Intelligence Sends analysis alerts, disabled by default Anonymous mode, or identified mode with a token

Secrets are never sent to the browser: the dashboard relays calls to the log store with the read token, on the server side.

What happens when a component stops

Stopped component Consequence
Log store The shipper keeps batches in a disk buffer (capped at 256 MB or 24 h) and resends them when the service returns, without duplicates
Shipper Decisions emitted by the WAF and the challenge during the outage are lost; access log reading resumes where it stopped
Hub No effect on dashboards
Intelligence No effect on Nginx: each instance stays autonomous
Redis In-progress statistics are lost when the analyzer or challenge restarts, as without Redis
Dashboard Nginx keeps serving traffic with the last loaded configuration

Choosing what to deploy

Need Components
A reverse proxy with an interface Nginx and dashboard
Detect and block abusive behavior + analyzer, blocklists, challenge, emulated WAF (enabled from the dashboard)
Control remote servers + agent on each server
Supervise several installations + Hub
Keep and query logs over time + log store (the shipper is managed by the dashboard)
Keep statistics after a restart + Redis

One version for the whole suite

All components carry the same version number. See Versions and updates.