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.11 · Changelog · Releases
- Target IPv4/IPv6 networks, individual clients, or PTR hostnames, with whitelist precedence and timezone-aware schedules.
- 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.
- 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.
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.
git clone https://github.com/StealthCat/blockinator-web.git
cd blockinator-webFor 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.
docker compose up -d --buildSQLite is the default. For MySQL, complete database setup before starting. Preserve .env and ./data, which contains SQLite data, TLS files, and Caddy state.
Open http://DOCKER-HOST:8080/ and sign in as admin with the password from .env.
- Add block lists or whitelists and assign them globally or to policy targets.
- Use Policy Tester to verify a decision.
- Configure your resolver plugin with endpoint
http://DOCKER-HOST:8080/api/v1/decisionand the API key from.envor Access & Security. - 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 caddyFrom 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 --buildReview 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.
| 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.
GNU General Public License v3.0.
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