Install ToutWAF with Docker and Compose
Run the control plane and the data plane in containers with Docker Compose, on Linux or a Mac: start, first-login credentials, upgrade and uninstall.
Which version you install
The public version is a development version, named 0.3.0-dev. Its name stays the same: each publication replaces the previous one, and a build identifier tells two builds apart. No stable version exists yet: it will only be published once every system and package has been tested end to end. The commands on this page therefore install from the dev channel. A development version can contain bugs: try it on a test site before relying on it.
At a glance
- One image runs the control plane (console and API) or the data plane, selected with TOUTWAF_ROLE; the compose file starts one of each.
- The files (the deploy folder) come with your ToutWAF distribution: they are not in the public repository, which holds binaries and installers only.
- On the very first start, the toutwaf-cp logs show once the secret console address and the generated username and password: copy them, they are written nowhere else.
- The console is published on 127.0.0.1 only: to reach it remotely, use an SSH tunnel, a VPN or a TLS reverse proxy with an allow-list. Never publish 9443 on a public interface.
The commands, step by step
Docker Compose on a Mac or Linux
Docker Compose on Linux or a Mac (Docker Desktop, OrbStack, Colima), with the all-in-one image (control plane and data plane). The files come with your ToutWAF distribution (the deploy folder, which is not in the public repository: that one holds binaries and installers only). The image packages prebuilt binaries per architecture (bin/amd64 or bin/arm64) and no image is published to a registry yet. Tested on Linux amd64 only; untested on a real Mac, where the client IP seen behind Docker Desktop is the Docker gateway address. The one-time credentials appear once in the control plane log.
cd deploy/docker
# bin/amd64/{toutwaf-cp,toutwaf-dp,toutwafctl} (Intel Mac, Linux x86-64)
# bin/arm64/{toutwaf-cp,toutwaf-dp,toutwafctl} (Apple Silicon, Linux ARM)
cp .env.example .env
docker compose up -d --build
docker compose logs toutwaf-cpUpgrade (containers)
Take a backup first. The Update button of the console cannot work in a container: replace the binaries in the bin folder (or the image, once one is published) and rebuild; the volumes, so your data, are kept.
docker compose up -d --buildUninstall
The first block removes the services, the binaries and the firewall rules added by ToutWAF, and keeps your data. The second one also deletes configuration, data and logs.
docker compose downdocker compose down -vWhat is not verified
We prefer to say it plainly.
- Tested end to end on Linux x86-64 only. An Intel Mac, an Apple Silicon Mac (linux/arm64) and Windows with Docker Desktop are not tested on real hardware.
- No image is published to a registry: building needs the prebuilt release binaries. Native macOS is not provided.
- The in-console update and the firewall helper do not work in a container: you update by replacing the image. A single control-plane instance, with SQLite.