# Blocky — Self-Hosted DNS Ad-Blocker & Privacy Proxy

> A fast and lightweight DNS proxy written in Go that blocks ads and trackers at the network level with support for DNS-over-HTTPS, conditional forwarding, and client-specific rules.

## Install

Save as a script file and run:

# Blocky — Self-Hosted DNS Ad-Blocker & Privacy Proxy

## Quick Use
```bash
docker run -d --name blocky 
  -p 53:53/udp -p 53:53/tcp -p 4000:4000 
  -v ./config.yml:/app/config.yml 
  spx01/blocky
# Point your router or device DNS to the server IP
```

## Introduction
Blocky is a lightweight DNS proxy and ad-blocker written in Go that acts as a network-level privacy filter. It resolves DNS queries using upstream servers while blocking domains found in configurable blocklists. Unlike Pi-hole, Blocky requires no database and runs as a single binary with a YAML configuration file, making it ideal for containers and minimal setups.

## What Blocky Does
- Blocks ads, trackers, and malware domains by filtering DNS queries against blocklists
- Supports DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) for encrypted upstream resolution
- Applies client-specific blocking rules based on IP address or subnet
- Provides conditional DNS forwarding for split-horizon setups with local domains
- Offers a REST API and Prometheus metrics for monitoring and automation

## Architecture Overview
Blocky is a stateless Go application that listens for DNS queries on UDP/TCP port 53. It evaluates each query against in-memory blocklists loaded at startup from remote URLs or local files. Allowed queries are forwarded to configured upstream resolvers with support for parallel queries and failover. Results are cached in memory with configurable TTLs. The configuration is a single YAML file defining upstream servers, client groups, blocklists, and custom DNS entries.

## Self-Hosting & Configuration
- Deploy as a single Docker container or standalone binary with minimal resource usage
- Define upstream DNS resolvers in `config.yml` under the `upstream` section
- Add blocklist URLs under `blocking.blackLists` grouped by category
- Configure client-specific rules by mapping IP ranges to blocking groups
- Enable the Prometheus endpoint and REST API for monitoring and management

## Key Features
- Single binary with no database dependency and YAML-only configuration
- DNS-over-HTTPS and DNS-over-TLS for encrypted upstream queries
- Client-group-based blocking with different rules per device or subnet
- Built-in DNS caching with configurable TTL and prefetching
- Prometheus metrics and REST API for integration with monitoring stacks

## Comparison with Similar Tools
- **Pi-hole** — Web UI with statistics dashboard; Blocky is lighter with no database and container-native design
- **AdGuard Home** — Feature-rich with DHCP and rewrites; Blocky focuses on DNS filtering with minimal footprint
- **CoreDNS** — General-purpose DNS server requiring plugins; Blocky is purpose-built for ad-blocking
- **Unbound** — Recursive resolver without blocking; Blocky adds filterable forwarding on top
- **NextDNS** — Cloud DNS filtering service; Blocky keeps all resolution local and private

## FAQ
**Q: How much memory does Blocky use?**
A: Typically 30-80 MB depending on the number of blocklist entries loaded. It runs well on a Raspberry Pi.

**Q: Can I use Blocky alongside Pi-hole?**
A: Yes, you can chain them or use Blocky as an upstream for Pi-hole, though running both is usually redundant.

**Q: How do I whitelist a specific domain?**
A: Add it to the `blocking.whiteLists` section in your config.yml under the appropriate group.

**Q: Does Blocky support custom DNS records?**
A: Yes, use the `customDNS` section to define A, AAAA, or CNAME records for local resolution.

## Sources
- https://github.com/0xERR0R/blocky
- https://0xerr0r.github.io/blocky

---
Source: https://tokrepo.com/en/workflows/2b274d5b-3cd4-11f1-9bc6-00163e2b0d79
Author: Script Depot