Install

• 1: Linux (systemd)
• 2: Docker Compose
• 3: Windows
• 4: macOS

1 - Linux (systemd)

Use this path on a Linux VM or bare metal host.

Unpack

tar -xzf cheesewaf-*-linux-amd64.tar.gz
cd cheesewaf-*

Replace amd64 with arm64 or loong64 when that is the CPU.

Install files

sudo install -m 0755 cheesewaf /usr/local/bin/cheesewaf
sudo ln -sf /usr/local/bin/cheesewaf /usr/local/bin/waf-cli

sudo mkdir -p /etc/cheesewaf /var/lib/cheesewaf /var/log/cheesewaf
sudo cp configs/cheesewaf.yaml /etc/cheesewaf/cheesewaf.yaml

sudo useradd --system --home /var/lib/cheesewaf --shell /usr/sbin/nologin cheesewaf
sudo chown -R cheesewaf:cheesewaf /etc/cheesewaf /var/lib/cheesewaf /var/log/cheesewaf

The Linux tarball includes systemd/cheesewaf.service.

sudo cp systemd/cheesewaf.service /etc/systemd/system/cheesewaf.service
sudo systemctl daemon-reload
sudo systemctl enable --now cheesewaf
sudo systemctl status cheesewaf

Open http://<host>:9443/setup and continue with Initialize.

Paths

Bind the data plane to a public address only after you have a site, an upstream, and a paranoia level you accept.

2 - Docker Compose

Use this path in a container host. docker compose build produces linux/amd64 or linux/arm64 for the host CPU.

The image runs as UID 10001. The root filesystem is read-only.

Compose file

The repository file is deploy/docker/docker-compose.yml. A minimal copy:

services:
  cheesewaf:
    image: cheesewaf:latest
    build:
      context: .
      dockerfile: deploy/docker/Dockerfile
    user: "10001:10001"
    restart: unless-stopped
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp:size=32m,mode=1777,noexec,nosuid,nodev
    ports:
      - "8080:8080"
      - "9443:9443"
    volumes:
      - cheesewaf-data:/var/lib/cheesewaf
      - cheesewaf-logs:/var/log/cheesewaf
    healthcheck:
      test: ["CMD", "/usr/local/bin/cheesewaf-entrypoint", "healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  cheesewaf-data:
  cheesewaf-logs:

Build context must be the CheeseWAF repository root when you use that Dockerfile.

Start

docker compose up -d
docker compose logs -f cheesewaf

Open https://<host>:9443/setup. The container uses a self-signed admin certificate by default. The first-run token is in the startup log.

docker compose down keeps the named volumes. Site config and SQLite live in cheesewaf-data.

3 - Windows

Windows has three shapes. They are not three different WAFs.

A. Single-file CLI

1. Download cheesewaf-*-windows-amd64.exe or the arm64 file.
2. Run:

.\cheesewaf-*-windows-amd64.exe serve --config .\cheesewaf.yaml --data-dir .\data
.\cheesewaf-*-windows-amd64.exe status
.\cheesewaf-*-windows-amd64.exe stop

The forwarding process does not need the installer. The Web UI assets live in web/dist next to the executable in zip / DMG / tar packages.

B. Portable zip

1. Unpack cheesewaf-*-windows-amd64.zip to a directory such as D:\CheeseWAF.
2. Run:

.\cheesewaf.exe serve --config .\configs\cheesewaf.yaml --data-dir .\data
.\cheesewaf.exe status
.\cheesewaf.exe stop

C. NSIS installer

1. Run CheeseWAF-*-windows-amd64-setup.exe or the arm64 setup.
2. Follow the wizard.
3. Uninstall keeps data\ by default.

The installer may register a Windows service (sc.exe create CheeseWAF …). Treat that as best-effort.

Local controller

cheesewaf-gui is not a second admin console. It only starts, stops, and opens the real management UI.

• Bind address: 127.0.0.1:17943
• Shows PID and running state
• Opens the Web console and the config folder
• Optional current-user autostart (HKCU\Run)

.\cheesewaf-gui.exe --config .\configs\cheesewaf.yaml --data-dir .\data

The browser opens http://127.0.0.1:17943/.

4 - macOS

DMG

1. Download cheesewaf-*-darwin-arm64.dmg (Apple Silicon) or cheesewaf-*-darwin-amd64.dmg (Intel).
2. Open the image and drag CheeseWAF into Applications.
3. Launch CheeseWAF from Launchpad or Applications.

The app starts the local controller. Use it to start, stop, and open the Web console.

Runtime data is under ~/Library/Application Support/CheeseWAF.

CLI tarball

If you only want the command line:

tar -xzf cheesewaf-*-darwin-arm64.tar.gz
cd cheesewaf-*
./cheesewaf serve --config ./configs/cheesewaf.yaml --data-dir ./data

Then open http://127.0.0.1:9443/setup.