Blockinator

Self-hosted DNS policy management with block lists, whitelists, schedules, and query history. Your DNS server sends query metadata; Blockinator returns an allow/block decision. Connect Technitium using the companion plugin.

Current source version: 1.20.19 · Changelog · Releases

Latest application release: v1.20.12

v1.20.12 fixes list editing and refresh reliability, repeated or stale toggle submissions, concurrent API key changes, client identity handling, MySQL query logging, and TLS configuration recovery. List and API key timestamps now use the configured timezone, and malformed requests receive appropriate errors. See the full changelog.

Back up your data before updating. Existing installations keep their settings; MySQL upgrades widen the query-name column automatically. Before migrating SQLite to MySQL, resolve any list or target names flagged as case-insensitive conflicts. The source version above also includes documentation updates after the application release.

Features

• Target IPv4/IPv6 networks, individual clients, or PTR hostnames, with whitelist precedence and up to 32 recurring schedule windows per list or target in a shared timezone.
• Apply scoped lists from the highest-priority scheduled target (endpoint → hostname → network), alongside global lists.
• Import lists from URLs, files, or pasted rules, or manage domains manually.
• Explain decisions with Policy Tester; search query history and view traffic and response-time statistics.
• Flush learned PTR identities and cached answers from System Settings → Runtime and refresh tracked clients in the background while preserving query history.
• Use SQLite or MySQL, managed HTTPS through Caddy, administrator accounts, and named API keys.
• Choose system, dark, or light themes in a responsive management console.

Quick start: Git clone and Docker Compose (recommended)

Build from stable main with Docker Compose. You need Docker Engine, Compose v2, Git, Bash, and OpenSSL on the Docker host. Use sudo for Docker if required.

1. Clone the repository

git clone https://github.com/StealthCat/blockinator-web.git
cd blockinator-web

2. Create first-run credentials

For a new installation, run this Bash block. It generates private credentials and refuses 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
POLICY_PORT=8080
HTTPS_PORT=8443
EOF
)

Keep .env private; view it locally with cat .env to retrieve your credentials. Set TZ to your IANA timezone and see .env.example for other options. If choosing your own credentials, use a unique password of at least 12 characters and API key of at least 24 characters. Existing database credentials are managed in Access & Security, not reset through .env.

3. Build and start Blockinator

docker compose up -d --build

SQLite is the default. For MySQL, complete database setup before starting. Preserve .env and ./data, which contains SQLite data, TLS files, and Caddy state.

4. Open and configure Blockinator

Open http://DOCKER-HOST:8080/ and sign in as admin with the password from .env.

1. Add block lists or whitelists and assign them globally or to policy targets.
2. Use Policy Tester to verify a decision.
3. Configure your resolver plugin with endpoint http://DOCKER-HOST:8080/api/v1/decision and the API key from .env or Access & Security.
4. Check activity in Query Log and Statistics.

Configure HTTPS under System Settings → HTTPS & TLS. The default HTTPS port is 8443; see the TLS guide for certificates, ACME, and port settings.

For status and troubleshooting:

docker compose ps
docker compose logs --tail=100 blockinator caddy

Updating

From your existing main checkout, stop the stack and back up your data, then update and rebuild:

docker compose stop
# Back up .env and ./data now; back up remote MySQL separately if used.
git pull --ff-only
docker compose up -d --build

Updating from 1.20.16 or earlier: API keys created before 1.20.17 stop authenticating. After updating, open Access & Security, rotate each key marked Rotation required (or create a new one), and update the API key in your DNS server plugin.

Review release notes and preserve local edits. If Git reports a conflict, resolve it without forcing or resetting the checkout. For existing tag checkouts, follow Moving to main first.

Guides and alternatives

Guide	Contents
Alternative installations	Docker Hub, fixed-version tags, upgrade paths, and startup troubleshooting
User guide	Targets, policy precedence, lists, schedules, query history, and settings
Operations	Databases, migration, HTTPS, environment variables, monitoring, and backups
Integration and API	Resolver configuration, authentication, and request/response examples
Development	Branch policy, tests, benchmarks, and releases

main contains stable code and current documentation; unreleased application work belongs on dev. Tags pin exact releases; Docker examples retain the previously published 1.20.1 image until a newer image is verified as published.

License

GNU General Public License v3.0.

Reddit User Reviews

Selected feedback from the r/technitium community:

“Vibe coded slop.
Hard pass.”
— u/Resistant4375

“AI Slop.”
— Anonymous

“So, built a $20 a month app.”
— u/Superb_Raccoon

“Thanks ChatGPT!”
— u/Key_Pace_2496

“it deserves to be called slop. I’d argue that “slop” is too kind”
— Anonymous