INSTALL / CONTAINER

Install DNS Deny with Docker Compose

Use the repository’s Dockerfile and Compose setup to run DNS Deny in a container. The image is built from source on your host.

1. Prepare the configuration

Install Docker with Compose support, then get the source:

git clone https://github.com/dre-zouhair/dns-deny.git
cd dns-deny

Edit deploy/config.toml before the first start. Set a unique api_key and restrict allowed DNS clients. Keep the API bound to 0.0.0.0 inside the container; Compose publishes it on host loopback.

2. Choose HTTP or HTTPS access

HTTP is enabled by default. After starting, open http://localhost:8083 on the Docker host. Set api_allow_insecure_http = false to require HTTPS. Existing state keeps its saved api_allow_insecure_http value. Changing it requires a planned saved-state migration or re-provisioning; editing the seed alone does not apply it. See state and restart behavior.

The admin backend is published on 127.0.0.1:8083, forwarding to container port 8080. To enforce HTTPS, put your host’s HTTPS proxy in front of that address. Trust the actual proxy peer IP seen inside Docker, usually a bridge gateway, with a /32 or /128 prefix.

Set api_trusted_proxy_cidrs in the initial seed or add DNS_API_TRUSTED_PROXY_CIDRS to the Compose environment for existing state. Use your actual peer address; keep the backend private.

3. Build and start

docker compose -f deploy/docker-compose.yml up --build -d
docker compose -f deploy/docker-compose.yml logs -f

For standard DNS, change both mappings to 53:53 and set DNS_PORT: "53". Enable the supplied NET_BIND_SERVICE capability if your runtime requires it. Test DNS separately from the dashboard.

Select features at build time

# Build a dashboard-only image, then start it.
docker compose -f deploy/docker-compose.yml build \
  --build-arg CARGO_BUILD_FLAGS="--no-default-features --features feat-web-ui"
docker compose -f deploy/docker-compose.yml up -d

# Or build a separate API-only image with scoring.
docker build -f deploy/Dockerfile -t dns-deny:api-scoring \
  --build-arg CARGO_BUILD_FLAGS="--no-default-features --features feat-json-api,feat-scoring" .

The tagged-image example only builds an image; configure its runtime deployment separately. For repeatable Compose rebuilds, save the argument under services.dns-deny.build.args:

args:
  CARGO_BUILD_FLAGS: "--no-default-features --features feat-web-ui"

A later plain build uses default features unless you save these arguments. Scoring also needs ml_scoring_enabled = true in saved configuration. Runtime DNS_* variables do not change compiled features.

4. Update without resetting

docker compose -f deploy/docker-compose.yml build
docker compose -f deploy/docker-compose.yml up -d

Back up the data volume before updating. make docker-rebuild deletes the named volume through down -v; use the commands above for routine updates. Seed edits do not replace settings already stored in SQLite.

Architecture and variants

This guide builds locally; it does not assume a published multi-architecture image. For the original Pi Zero, use the ARMv6 package or binary. The Dockerfile accepts CARGO_BUILD_FLAGS for custom feature builds; see the Dockerfile and the feature matrix.

Deployment and backup guide · Compose configuration