Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/proteo5/waf-autoblock/llms.txt

Use this file to discover all available pages before exploring further.

Docker Compose is the recommended deployment method for servers. It keeps the container configuration declarative, makes upgrades and rollbacks a single command, and handles the volume mount and restart policy automatically. The repository ships two Compose files: docker-compose.yml for building from source and docker-compose.hub.yml for pulling the published Docker Hub image.

​
Compose Files

The repository provides two Compose files serving different purposes:

docker-compose.yml

Builds the image locally from the repository source using the Dockerfile. The default image tag is local. Use this file during development when you need to test uncommitted changes.

docker-compose.hub.yml

Pulls the image from Docker Hub (proteo5/waf-autoblock). Defaults to the latest tag but respects the DOCKER_TAG environment variable to pin a specific version. Use this file for all server deployments.
Both files load environment variables from waf-autoblock.env by default and mount ./data into the container at /app/data for SQLite persistence.

​
Server Install with Compose

1

Create the server folder and data directory

Set up the working directory that will hold the Compose file, env file, and persistent data:
mkdir -p /opt/waf-autoblock/data
2

Copy the Compose file to the server

Place docker-compose.hub.yml in the working directory. This is the only Compose file needed for server deployments:
cp docker-compose.hub.yml /opt/waf-autoblock/
3

Create the environment file

Copy .env.example from the repository and fill in your Cloudflare credentials, rule IDs, and any tuning values:
cp .env.example /opt/waf-autoblock/waf-autoblock.env
Open waf-autoblock.env and set your real values for Cloudflare__ApiToken, Cloudflare__ZoneTag, Cloudflare__AccountId, Cloudflare__BlocklistId, and at least one Rules__0__RuleId.
4

Pull the image and start the service

Pin the versioned tag, pull the image, and bring the service up in detached mode:
cd /opt/waf-autoblock
export DOCKER_TAG=v0.1.0-rc1
docker compose -f docker-compose.hub.yml pull
docker compose -f docker-compose.hub.yml up -d
5

Verify the deployment

Tail the container logs and query the status endpoint to confirm a healthy start:
docker compose -f docker-compose.hub.yml logs --tail 100
curl http://localhost:8080/status
A successful start shows SQLite initialization, polling startup, and no exception traces in the logs. The status endpoint returns JSON with "running": true.

​
Local Development Build

For local development, run from the repository root. Compose will build the image from source before starting the container: 
docker compose up --build
The service listens on http://localhost:8080. The ./data directory is mounted automatically so the SQLite database persists between runs. Stop the service with Ctrl+C; the data directory remains intact.

​
Pinning a Tag

The DOCKER_TAG environment variable controls which image version Compose pulls and runs. Set it before calling docker compose to pin a specific release: 
export DOCKER_TAG=v0.1.0-rc1
docker compose -f docker-compose.hub.yml pull
docker compose -f docker-compose.hub.yml up -d
To use the latest tag instead, unset the variable before running Compose: 
unset DOCKER_TAG
docker compose -f docker-compose.hub.yml pull
docker compose -f docker-compose.hub.yml up -d
The recommended promotion flow is to validate a versioned tag first, then unset DOCKER_TAG and promote to latest only after that validation passes.

​
Custom Env Filename

By default, both Compose files load environment variables from waf-autoblock.env in the working directory. If you need to use a different filename — for example when managing multiple environments on the same server — set RUNTIME_ENV_FILE before running Compose: 
export RUNTIME_ENV_FILE=/opt/waf-autoblock/production.env
docker compose -f docker-compose.hub.yml up -d
The RUNTIME_ENV_FILE variable maps directly to the env_file.path field in the Compose definition, so any valid path accepted by Docker Compose is supported.

​
Dollar Sign Escaping

In Docker Compose env files, the $ character must be escaped as $$. So $auto_blocked_ips in config becomes $$auto_blocked_ips in the .env file. The service receives the literal value $auto_blocked_ips and resolves it to the list UUID.
This matters for Cloudflare__BlocklistId when you reference the list by its symbolic name. The .env.example file already has the correct escaped form: 
Cloudflare__BlocklistId=$$auto_blocked_ips
Do not remove the double $$ — a single $ would be interpreted as a Compose variable substitution and the value passed to the container would be empty.

Build docs developers (and LLMs) love

Get started for freeTalk to us