Deploy with Docker Compose
This guide runs NullWard on a single Linux host with Docker Compose. The stack has three containers, plus an optional fourth for malware scanning:
| Container | Image |
|---|---|
nullward | harbor.sageisg.com/nullward/waf |
surrealdb | surrealdb/surrealdb:v2 (NullWard 0.6.88 and later also run on surrealdb/surrealdb:v3) |
valkey | valkey/valkey:8-alpine |
clamav (optional) | clamav/clamav |
Before you start
- A Linux host with Docker Engine and the Docker Compose plugin.
- DNS records for the domains you want to protect, pointing at this host.
- Ports 80 and 443 reachable from the internet. Port 80 is needed for HTTP-to-HTTPS redirects and for Let's Encrypt HTTP-01 validation.
- A trusted network path to the host for administrators: an office network, VPN or bastion host. You'll use it to reach the management port.
1. Create the project directory
mkdir -p /opt/nullward && cd /opt/nullward
2. Create the .env file
NullWard reads only a few environment variables, enough to start up and reach its database. Everything else is configured in the admin dashboard and stored in the database.
Generate the secrets:
openssl rand -base64 32 # use for NULLWARD_JWT_SECRET
openssl rand -base64 32 # use for NULLWARD_ENCRYPTION_KEY
Create /opt/nullward/.env:
# Required
NULLWARD_JWT_SECRET=<first generated value>
NULLWARD_ENCRYPTION_KEY=<second generated value>
NULLWARD_ADMIN_PASSWORD=<a strong password for the first admin account>
# Optional (defaults shown)
NULLWARD_ADMIN_USERNAME=admin
NULLWARD_DB_USERNAME=root
NULLWARD_DB_PASSWORD=<a strong database password>
NULLWARD_LOG_LEVEL=info
Protect it: chmod 600 .env.
[!WARNING]
NULLWARD_ENCRYPTION_KEYencrypts the secrets NullWard stores in the database: identity-provider client secrets, API keys for threat feeds and other providers, DNS credentials, tunnel keys and uploaded private keys. It must be base64 that decodes to exactly 32 bytes, which is what theopensslcommand above produces. Back it up. If you lose it, those secrets can't be decrypted. Every node of a cluster needs the same key and the same JWT secret.
[!NOTE] The admin account named by
NULLWARD_ADMIN_USERNAMEis created on first start. Its password is reset toNULLWARD_ADMIN_PASSWORDevery time NullWard starts, so change the password in.envand restart, not in the dashboard.
All environment variables
| Variable | Default | Purpose |
|---|---|---|
NULLWARD_JWT_SECRET | (required) | Signs admin sessions |
NULLWARD_ENCRYPTION_KEY | (required) | Encrypts secrets at rest (base64, 32 bytes) |
NULLWARD_ADMIN_PASSWORD | (required) | Password of the bootstrap admin account |
NULLWARD_ADMIN_USERNAME | admin | Username of the bootstrap admin account |
NULLWARD_DB_HOST / NULLWARD_DB_PORT | 127.0.0.1 / 7051 | SurrealDB address |
NULLWARD_DB_NAMESPACE / NULLWARD_DB_DATABASE | nullward / waf | SurrealDB namespace and database |
NULLWARD_DB_USERNAME / NULLWARD_DB_PASSWORD | root / root | SurrealDB credentials |
NULLWARD_KEYDB_HOST / NULLWARD_KEYDB_PORT | 127.0.0.1 / 7053 | Valkey address (the variable names are historical) |
NULLWARD_KEYDB_PASSWORD / NULLWARD_KEYDB_DB | (empty) / 0 | Valkey password and database number |
NULLWARD_WEB_HOST / NULLWARD_WEB_PORT | 0.0.0.0 / 7052 | Management (admin dashboard and API) listener |
NULLWARD_PROXY_HTTP_ADDR | 0.0.0.0:7050 | Proxy HTTP listener |
NULLWARD_PROXY_ADDR | 0.0.0.0:7443 | Proxy HTTPS listener (and HTTP/3 over UDP) |
NULLWARD_HTTPS_REDIRECT_PORT | (empty = 443) | Public HTTPS port used in HTTP-to-HTTPS redirects |
NULLWARD_LOG_LEVEL | info | debug, info, warn or error |
3. Create docker-compose.yml
Replace 10.0.0.5 with an address on your trusted management network (see Protect the management port).
services:
nullward:
image: harbor.sageisg.com/nullward/waf:latest # or pin a version, e.g. v0.6.79-beta
restart: unless-stopped
env_file: .env
environment:
NULLWARD_DB_HOST: surrealdb
NULLWARD_DB_PORT: "8000"
NULLWARD_KEYDB_HOST: valkey
NULLWARD_KEYDB_PORT: "6379"
ports:
- "80:7050" # proxy, HTTP
- "443:7443" # proxy, HTTPS
- "443:7443/udp" # HTTP/3 (only needed if you turn it on)
- "10.0.0.5:7052:7052" # management: trusted network only
- "7055:7055/udp" # application tunnels (only needed if you use them)
# Clustering only (high availability), reachable from the other nodes only:
# - "7059:7059/tcp"
# - "7059:7059/udp"
stop_grace_period: 50s # lets in-flight requests finish on stop/upgrade
depends_on:
surrealdb:
condition: service_healthy
valkey:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-q", "--spider", "http://localhost:7052/health"]
interval: 10s
timeout: 5s
retries: 5
start_period: 15s
surrealdb:
image: surrealdb/surrealdb:v2
restart: unless-stopped
user: root
command: start --user ${NULLWARD_DB_USERNAME:-root} --pass ${NULLWARD_DB_PASSWORD:-root} --bind 0.0.0.0:8000 rocksdb:/data/nullward.db
volumes:
- surrealdb_data:/data
healthcheck:
test: ["CMD", "/surreal", "isready"]
interval: 5s
timeout: 5s
retries: 10
start_period: 5s
valkey:
image: valkey/valkey:8-alpine
restart: unless-stopped
command: valkey-server --appendonly yes
volumes:
- valkey_data:/data
healthcheck:
test: ["CMD", "valkey-cli", "ping"]
interval: 5s
timeout: 5s
retries: 10
volumes:
surrealdb_data:
valkey_data:
The database and Valkey publish no ports. Only NullWard talks to them, over the Compose network.
Optional: malware scanning
To scan uploads with ClamAV, add this service:
clamav:
image: clamav/clamav:latest
restart: unless-stopped
volumes:
- clamav_data:/var/lib/clamav
Add clamav_data: under volumes:. Then, in the dashboard, set Settings > Malware Scanner > ClamAV Host to clamav. ClamAV takes a few minutes to download its signatures on first start.
4. Start the stack
docker compose pull
docker compose up -d
docker compose ps # all services should become "healthy"
docker compose logs -f nullward
5. Sign in
From a machine on your trusted network, open http://10.0.0.5:7052 (your management address) and sign in with NULLWARD_ADMIN_USERNAME and NULLWARD_ADMIN_PASSWORD.
The NullWard sign-in page
Then:
- Settings > Authentication > Admin External URL: set the address administrators use to reach the dashboard, for example
https://waf-admin.example.com. It's used for admin single sign-on redirects and in tunnel install commands. - Settings > License: paste your signed license token, if you have one. See License.
- Services > Services > Add Service: protect your first application. See Services.
Protect the management port
Port 7052 serves the admin dashboard and the admin API. Anyone who can reach it can try to sign in, so it's meant to be reached from trusted IP addresses only. That's why it's a separate port from the public proxy ports (80/443): you can firewall it independently. Never publish it to the internet.
Use one or more of these layers:
- Bind it to a private interface. In
docker-compose.yml, publish it on an internal or VPN address ("10.0.0.5:7052:7052"), not on all addresses. To allow access only through SSH, bind it to localhost ("127.0.0.1:7052:7052") and use an SSH port forward. - Firewall it. At your network or cloud firewall, allow TCP 7052 only from your admin networks. A host firewall such as firewalld or ufw isn't enough on its own: Docker writes its own iptables rules for published ports, and they bypass those tools. Binding the port to a private address, as above, is the most dependable option. Test from an outside address that the port is closed.
- Turn on the Admin IP Allowlist. Under Settings > Security, list the IPs and CIDR ranges allowed to use the dashboard and API. Localhost is always allowed. Changes apply within 30 seconds.
- Use single sign-on. Add an admin OIDC provider (Microsoft, Google or any OIDC provider) under Settings > Authentication > Admin OIDC Providers. See Authentication.
Reach the management port over SSH
If the management port is bound to 127.0.0.1 on the NullWard host, administrators reach it through an SSH port forward. Nothing extra is exposed: only SSH needs to be reachable.
From your workstation:
ssh -N -L 7052:127.0.0.1:7052 admin@waf-host.example.com
Leave that running, then browse to http://localhost:7052.
-L 7052:127.0.0.1:7052forwards port 7052 on your workstation to port 7052 on the NullWard host's loopback address.-Nopens the tunnel without starting a remote shell.- If port 7052 is already in use on your workstation, pick another local port, for example
-L 17052:127.0.0.1:7052, and browse tohttp://localhost:17052. - Through a bastion (jump) host:
ssh -N -J admin@bastion.example.com -L 7052:127.0.0.1:7052 admin@waf-host.example.com.
On Windows, the built-in OpenSSH client accepts the same command. In PuTTY, go to Connection > SSH > Tunnels, enter source port 7052 and destination 127.0.0.1:7052, and click Add before you connect.
To keep a forward in your SSH config instead, add this to ~/.ssh/config:
Host nullward-admin
HostName waf-host.example.com
User admin
LocalForward 7052 127.0.0.1:7052
Then run ssh -N nullward-admin.
[!NOTE] When you sign in through the forward, set Admin External URL (Settings > Authentication) to the address administrators actually use, such as
http://localhost:7052, so that admin single sign-on redirects come back through the tunnel.
Open the public ports
| Port | Protocol | When |
|---|---|---|
| 80 | TCP | Always (also used by the one-command tunnel install) |
| 443 | TCP | Always |
| 443 | UDP | Only if you turn on HTTP/3 |
| 7055 | UDP | Only if you use application tunnels |
| 7059 | TCP and UDP | Only between cluster nodes, if you use high availability |
| 7057 | UDP | Only between cluster nodes of a cluster still on the WireGuard mesh engine (formed before 0.6.109) |
For example, with firewalld:
firewall-cmd --permanent --add-service=http --add-service=https
firewall-cmd --permanent --add-port=443/udp # HTTP/3
firewall-cmd --permanent --add-port=7055/udp # tunnels
firewall-cmd --reload
Behind another load balancer or CDN
If NullWard sits behind a CDN or load balancer, turn on Settings > Proxy & Session Defaults > Trust Forwarded Headers so NullWard sees the real client IP from X-Forwarded-For. Leave it off when NullWard faces the internet directly, or clients can spoof their address.
Upgrade
cd /opt/nullward
docker compose pull nullward
docker compose up -d nullward
NullWard finishes in-flight requests before it stops (up to 20 seconds), which is why the Compose file sets stop_grace_period: 50s. Read the release notes before upgrading. Pin a version tag in production so upgrades happen only when you choose.
Back up
Back up all three of these:
- The
.envfile. It holds the encryption key and the JWT secret. Without the encryption key, the secrets stored in the database can't be decrypted. - The
surrealdb_datavolume (or a SurrealDB export). It holds all configuration. To move it from SurrealDB 2 to 3, see Migrate from SurrealDB 2 to 3. - The
valkey_datavolume. It holds the ML WAF's training data: the per-service traffic profiles it has learned and your ML tuning decisions. Losing it means the ML WAF has to relearn your traffic. It also holds rate-limit counters and caches, which rebuild on their own.
The Compose file runs Valkey with --appendonly yes, so its data is written to the volume continuously. For a consistent copy, stop the stack (docker compose stop), copy the volumes, then start it again. Or snapshot the disk that holds them.

