Deploying Blocky

Introduction

Blocky is a DNS proxy and ad blocker for the local network written in Go. It acts as a DNS sinkhole, blocking ads, trackers, and malicious domains at the DNS level before they can load in your browser or applications.

Designed as a lightweight alternative to Pi-hole, Blocky runs efficiently with minimal resources while providing powerful filtering capabilities, conditional forwarding, and detailed query logging.

Key highlights of Blocky:

• DNS-Level Blocking: Block ads and trackers network-wide
• Multiple Blocklists: Support for various blocklist formats
• Conditional Forwarding: Route specific domains to different resolvers
• Query Logging: Detailed logging with Prometheus metrics
• DoH/DoT Support: DNS over HTTPS and DNS over TLS upstream
• Client Groups: Different blocking rules per client
• Low Resource Usage: Efficient Go implementation
• REST API: Query and configure via HTTP API
• Caching: Built-in DNS response caching
• DNSSEC Validation: Secure DNS responses
• Configuration Reload: Update config without restart

This guide walks through deploying Blocky on Klutch.sh using Docker for network-wide ad blocking.

Why Deploy Blocky on Klutch.sh

Deploying Blocky on Klutch.sh provides several advantages:

Remote DNS: Use as a DoH/DoT resolver from anywhere.

Privacy: Control your DNS queries without relying on third parties.

Always Available: 24/7 DNS resolution with ad blocking.

API Access: Query logs and stats via REST API.

Configuration Management: Version-controlled blocklists and settings.

Secure Access: HTTPS by default for DoH endpoints.

Prerequisites

Before deploying Blocky on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic understanding of Docker and containerization
• Familiarity with DNS concepts
• Devices that can be configured to use custom DNS

Understanding Blocky Architecture

Blocky operates as a DNS middleware:

DNS Server: Listens for DNS queries on port 53.

Blocking Engine: Checks queries against blocklists.

Upstream Resolvers: Forwards non-blocked queries to upstream DNS.

API Server: Provides REST endpoints for management.

Logging: Records queries for analysis.

Preparing Your Repository

Create a GitHub repository for your Blocky deployment.

Repository Structure

blocky-deploy/
├── Dockerfile
├── config.yaml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for Blocky:

FROM spx01/blocky:latest

# Copy configuration
COPY config.yaml /app/config.yml

# Expose ports
# DNS
EXPOSE 53/tcp 53/udp
# HTTP API
EXPOSE 4000
# DoH
EXPOSE 443

# The base image includes the entrypoint

Configuration File

Create config.yaml with your Blocky configuration:

upstream:
  default:
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query

blocking:
  blackLists:
    ads:
      - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
      - https://adaway.org/hosts.txt
      - https://v.firebog.net/hosts/AdguardDNS.txt
    malware:
      - https://raw.githubusercontent.com/RPiList/specials/master/Blocklists/malware
    trackers:
      - https://v.firebog.net/hosts/Easyprivacy.txt
  whiteLists:
    ads:
      - https://raw.githubusercontent.com/anudeepND/whitelist/master/domains/whitelist.txt
  clientGroupsBlock:
    default:
      - ads
      - malware
      - trackers
  blockType: zeroIp
  blockTTL: 1m
  refreshPeriod: 4h

caching:
  minTime: 5m
  maxTime: 30m
  prefetching: true

queryLog:
  type: console
  target: ""
  logRetentionDays: 7

prometheus:
  enable: true
  path: /metrics

httpPort: 4000
httpsPort: 443

ports:
  dns: 53
  http: 4000
  https: 443

Environment Variables Reference

Variable	Required	Default	Description
BLOCKY_CONFIG	No	/app/config.yml	Path to configuration file
TZ	No	UTC	Timezone for logging

Deploying Blocky on Klutch.sh

Customize Your Blocklists

Edit config.yaml to include your preferred blocklists and settings.

Push Your Repository to GitHub

Initialize and push your configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “blocky” or “dns”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP for the API and DoH:

• Select HTTP as the traffic type
• Set the internal port to 4000 for API
• Configure port 443 for DoH if needed

Note: DNS queries (port 53) require UDP/TCP support.

Deploy Your Application

Click Deploy to build and start Blocky.

Configure Your Devices

Point devices to use your Blocky instance as DNS resolver.

Using Blocky

DNS-over-HTTPS

Configure DoH in browsers or devices:

https://your-blocky.klutch.sh/dns-query

API Endpoints

Query the REST API:

# Get blocking status
curl https://your-blocky.klutch.sh/api/blocking/status

# Disable blocking temporarily
curl -X PUT https://your-blocky.klutch.sh/api/blocking/disable?duration=5m

# Enable blocking
curl -X PUT https://your-blocky.klutch.sh/api/blocking/enable

# Query logs
curl https://your-blocky.klutch.sh/api/query

Prometheus Metrics

Scrape metrics for monitoring:

https://your-blocky.klutch.sh/metrics

Blocklist Management

Adding Blocklists

Add more blocklists in config:

blocking:
  blackLists:
    ads:
      - https://example.com/blocklist.txt

Whitelist Domains

Prevent false positives:

blocking:
  whiteLists:
    ads:
      - |
        example.com
        trusted-domain.com

Client-Specific Rules

Different rules per client:

blocking:
  clientGroupsBlock:
    default:
      - ads
      - malware
    kids-devices:
      - ads
      - malware
      - adult

Advanced Configuration

Conditional Forwarding

Route specific domains:

conditional:
  mapping:
    local.network: 192.168.1.1
    company.internal: 10.0.0.1

Custom DNS Entries

Define local DNS records:

customDNS:
  mapping:
    server.home: 192.168.1.100
    nas.home: 192.168.1.200

DNSSEC Validation

Enable DNSSEC:

dnsSec:
  enable: true

Monitoring and Logging

Query Logging

Configure logging output:

queryLog:
  type: mysql
  target: user:password@tcp(host:3306)/database
  logRetentionDays: 30

Grafana Dashboard

Use Prometheus metrics with Grafana:

1. Add Prometheus data source
2. Import Blocky dashboard
3. Monitor blocking statistics

Log Analysis

Analyze blocked queries:

• Review top blocked domains
• Identify false positives
• Track blocking effectiveness

Troubleshooting Common Issues

Queries Not Resolving

Solutions:

• Verify upstream DNS servers are accessible
• Check Blocky logs for errors
• Confirm DNS port is reachable

Legitimate Site Blocked

Solutions:

• Add domain to whitelist
• Check which blocklist caused the block
• Adjust client group settings

High Latency

Solutions:

• Enable caching with longer TTLs
• Use faster upstream resolvers
• Check network connectivity

Additional Resources

• Blocky Documentation
• Blocky GitHub Repository
• The Big Blocklist Collection
• Steven Black’s Hosts

Conclusion

Deploying Blocky on Klutch.sh gives you a powerful, self-hosted DNS proxy with comprehensive ad-blocking capabilities. With support for DNS-over-HTTPS, flexible blocklist management, and client-specific rules, Blocky provides network-wide protection from ads, trackers, and malware while keeping your DNS queries private.