Caddy-WAF as Docker Container

[flyboy1]

How to get files from /app as Volume Mounts so i can edit rules.json or ip_blacklist.json in Host folder and don't loose changes?

Exists some best practice to auto update blacklist files on using docker container?

Best regards
Franky

[fabriziosalmi]

You can mount host path or prepare a script to inject the updated files into the caddyfile, it should recognize and reload. Let mw know if everything goes flawlessy! TIA

[fabriziosalmi]

Hi @flyboy1, here is the typical setup.

Mount Caddyfile and the JSON state files as files (not directories) so you can edit them on the host without losing changes when the container is recreated:

services:
  caddy-waf:
    image: ghcr.io/fabriziosalmi/caddy-waf:latest
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./rules.json:/app/rules.json
      - ./ip_blacklist.json:/app/ip_blacklist.json
      - ./dns_blacklist.json:/app/dns_blacklist.json
      - caddy_data:/data
      - caddy_config:/config
    ports:
      - "80:80"
      - "443:443"

volumes:
  caddy_data:
  caddy_config:

For auto-updating blacklists, two patterns work well:

1. Cron on the host — a scheduled curl that overwrites the mounted file with the latest upstream blacklist. Caddy reloads rules automatically when the file changes — see docs/dynamicupdates.md.
2. Sidecar container — a small companion running the update script on a schedule, writing to the same volume.

Full Docker reference: docs/docker.md.

[donserdal]

Will the Image be the new way to install it with docker? docker.md still states building it yourself?

[fabriziosalmi]

Hi @flyboy1, @donserdal — apologies for how long this took, and thank you both for the patience.

@donserdal was right to push back. The image I pointed at in April did not exist: nothing in this repository ever built or published one, so that compose file could not have worked. docs/docker.md still said "build it yourself" because that was the only truth available.

It exists now.

docker pull ghcr.io/fabriziosalmi/caddy-waf:0.3.10

Published on release tags for linux/amd64 and linux/arm64. Available tags are 0.3.10, 0.3 and latest — note there is no v prefix on the image tag, unlike the Go module version. Pin the exact version rather than latest: this project shipped several security fixes today, and latest gives you no way to name the image you actually tested against.

Mounting your files

To @flyboy1's original question — mount the JSON and blacklist files individually, as files rather than directories, so editing them on the host survives the container being recreated:

services:
  caddy-waf:
    image: ghcr.io/fabriziosalmi/caddy-waf:0.3.10
    ports:
      - "8080:8080"
    volumes:
      - ./Caddyfile:/app/Caddyfile:ro
      - ./rules.json:/app/rules.json
      - ./ip_blacklist.txt:/app/ip_blacklist.txt
      - ./dns_blacklist.txt:/app/dns_blacklist.txt

On auto-updating the blacklists: the WAF watches those paths and reloads them when they change, so a cron job that rewrites the file on the host is enough — no container restart needed.

One caveat, and please read it before wiring up that cron. Hot reload deadlocked the server on every release before v0.3.9: the reload path blocked while holding a lock every request needs, so the process silently stopped answering. A job rewriting a blacklist on a schedule would have been the fastest way to hit it. Fixed now, but do not run that setup on an older build.

Also worth knowing

docker build . did not build your local checkout until v0.3.10 — the Dockerfile cloned this repository from GitHub and compiled whatever was on main. So if either of you ever built locally to test a change, you were testing something else. That is fixed, and CI now builds the image on every pull request and checks that caddy list-modules actually reports http.handlers.waf.

Several defects in the blacklist path were found and fixed today, published as GHSA-w6gv-76q4-prqg. Start from v0.3.10.