stealthcat128/blockinator repository overview

⁠Blockinator

Self-hosted DNS policy management for your network.

Manage blocklists, whitelists, clients, schedules, and DNS query history through a responsive web console. Your DNS resolver sends query metadata to Blockinator, which returns an allow/block decision. Your DNS server continues to resolve queries.

Source & documentation⁠ · Releases⁠ · Report an issue⁠

⁠Features

• Flexible targeting: IPv4/IPv6 networks, individual clients, and PTR hostnames, with whitelist precedence.
• Scheduled policies: up to 32 recurring windows per list or target, with timezone-aware matching.
• List management: import from URLs, files, or pasted rules; add domains manually.
• Policy visibility: explain decisions with Policy Tester, browse query history, and view traffic and response-time statistics.
• Client identity tools: background PTR resolution and cache flushing while preserving query history.
• Storage options: SQLite by default or an external MySQL database.
• Access controls: administrator accounts and named API keys.
• Managed HTTPS: optional Caddy deployment with certificate and ACME controls.
• Responsive console: system, dark, and light themes.

⁠Image tags and platforms

Images support Linux AMD64 (linux/amd64) and Linux ARM64 (linux/arm64). Docker selects the matching platform automatically.

Docker image tags omit the v: use stealthcat128/blockinator:1.20.12. GitHub release tags include it: v1.20.12.

docker pull stealthcat128/blockinator:1.20.12

Pulling an image does not update an already-running container. Recreate the container or Compose service to use it.

⁠Quick start: standalone Docker

This starts the application over HTTP. For built-in HTTPS and certificate management, use the Compose setup below.

On a Docker host with Bash and OpenSSL:

mkdir -p blockinator
cd blockinator

# Generate private first-run credentials; refuse to overwrite an existing .env.
(
  set -eu
  umask 077
  set -o noclobber
  admin_password=$(openssl rand -hex 24)
  policy_api_key=$(openssl rand -hex 32)
  cat > .env <<EOF
ADMIN_USERNAME=admin
ADMIN_PASSWORD=$admin_password
POLICY_API_KEY=$policy_api_key
DATABASE_BACKEND=sqlite
TZ=UTC
EOF
)

docker run -d \
  --name blockinator \
  --restart unless-stopped \
  --env-file ./.env \
  -e FORWARDED_ALLOW_IPS=127.0.0.1 \
  -p 8080:8080 \
  -v blockinator-data:/data \
  stealthcat128/blockinator:1.20.12

Open http://DOCKER-HOST:8080/⁠ and sign in as admin using the generated password in .env. View the file locally with cat .env; keep it private. Set TZ to your IANA timezone.

There is no default password. If choosing your own credentials, use a unique password of at least 12 characters and an API key of at least 24 characters. After initialization, manage credentials in Access & Security; changing bootstrap values in .env does not reset existing database credentials.

The named volume blockinator-data persists SQLite data in /data. Keep that volume when replacing the container. To change the host port, use a mapping such as -p 8180:8080.

⁠Docker Compose with managed HTTPS

Use the release’s Compose and Caddy configuration with the matching prebuilt image. Requirements: Docker Engine, Compose v2, Git, Bash, and OpenSSL.

git clone --branch v1.20.12 --single-branch https://github.com/StealthCat/blockinator-web.git
cd blockinator-web

Create a private .env using the credential-generation block above, or preserve your existing deployment’s file.

Create an image override:

cat > docker-compose.hub.yml <<'EOF'
services:
  blockinator:
    image: stealthcat128/blockinator:1.20.12
EOF

docker compose -f docker-compose.yml -f docker-compose.hub.yml pull
docker compose -f docker-compose.yml -f docker-compose.hub.yml up -d --no-build

Use both Compose files for subsequent commands. Caddy runs as a separate container; it is not bundled into this image.

Open http://DOCKER-HOST:8080/⁠. Configure HTTPS in System Settings → HTTPS & TLS; the default HTTPS host port is 8443. Preserve .env and ./data, including the database, TLS files, and Caddy state.

HTTPS and TLS guide⁠

⁠Connect your DNS resolver

1. Create blocklists or whitelists and assign them globally or to policy targets.
2. Verify a decision with Policy Tester.
3. Configure the resolver plugin with http://DOCKER-HOST:8080/api/v1/decision and an active API key.
4. Check Query Log and Statistics to confirm traffic.

Use your configured HTTPS endpoint when HTTPS is enabled.

Technitium companion plugin⁠ · Integration and API guide⁠

⁠Configuration

For MySQL, configure the MYSQL_* variables and complete database setup before startup. Run one application process; multiple workers or replicas require shared policy coordination.

All environment options⁠ · Database setup and operations⁠

⁠Updating

Back up .env and application data while the stack is stopped. Back up external MySQL separately. Read the release notes before upgrading, and keep deployment configuration and image versions matched.

For the Compose setup:

docker compose -f docker-compose.yml -f docker-compose.hub.yml stop
# Back up .env and ./data now; back up remote MySQL separately.
git fetch origin tag v1.20.12
git checkout --detach v1.20.12
# Set the override image to stealthcat128/blockinator:1.20.12.
docker compose -f docker-compose.yml -f docker-compose.hub.yml pull
docker compose -f docker-compose.yml -f docker-compose.hub.yml up -d --no-build

Preserve local configuration edits when changing release checkouts. For later releases, substitute the new Git tag and matching image tag.

Version 1.20.12 improves list editing and refresh reliability, API key concurrency, client identity handling, MySQL query logging, request validation, and TLS recovery. MySQL upgrades widen the query-name column automatically. SQLite-to-MySQL migration now detects case-insensitive list and target name conflicts before modifying the destination.

Release notes⁠ · Changelog⁠

⁠Troubleshooting and support

# Standalone Docker
docker logs --tail=100 blockinator
docker inspect --format '{{.State.Health.Status}}' blockinator

# Compose deployment
docker compose -f docker-compose.yml -f docker-compose.hub.yml ps
docker compose -f docker-compose.yml -f docker-compose.hub.yml logs --tail=100 blockinator caddy

User guide⁠ · Operations and backups⁠ · GitHub issues⁠

⁠License

GNU General Public License v3.0⁠