Codakey
Play
← Back to blocky

How to Deploy & Use blocky

Blocky Deployment and Usage Guide

1. Prerequisites

System Requirements:

  • Operating System: Linux, macOS, Windows (with Go support)
  • Architecture: x86-64 or ARM (including Raspberry Pi)
  • Runtime: Go 1.21 or later (for building from source)
  • Docker: Optional, for containerized deployment
  • Network: Local network access for DNS proxy functionality

Optional Dependencies:

  • Prometheus: For metrics collection
  • Grafana: For visualization (dashboard templates provided)
  • MySQL/MariaDB/PostgreSQL/Timescale: For query logging
  • Kubernetes: For Helm chart deployment

2. Installation

Option A: Docker (Recommended)

# Pull the latest image
docker pull spx01/blocky:latest

# Or pull a specific version
docker pull spx01/blocky:v0.24

# Run with default configuration
docker run -p 53:53/tcp -p 53:53/udp -p 4000:4000 \
  -v $(pwd)/config.yml:/app/config.yml \
  spx01/blocky:latest

Option B: Binary Release

# Download latest binary from GitHub releases
# Choose appropriate architecture:
# Linux x86-64
wget https://github.com/0xERR0R/blocky/releases/latest/download/blocky_linux_amd64.tar.gz

# Linux ARM (Raspberry Pi)
wget https://github.com/0xERR0R/blocky/releases/latest/download/blocky_linux_arm64.tar.gz

# Extract and install
tar -xzf blocky_linux_amd64.tar.gz
sudo cp blocky /usr/local/bin/
sudo chmod +x /usr/local/bin/blocky

Option C: Build from Source

# Clone the repository
git clone https://github.com/0xERR0R/blocky.git
cd blocky

# Build the binary
make build

# The binary will be at ./dist/blocky

3. Configuration

Basic Configuration File (config.yml)

Create a minimal configuration file:

upstream:
  default:
    - 1.1.1.1
    - 8.8.8.8

blocking:
  blackLists:
    ads:
      - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
    malware:
      - https://mirror1.malwaredomains.com/files/justdomains

clientGroupsBlock:
  default:
    - ads
    - malware

port: 53
httpPort: 4000

Advanced Configuration Options

IP Version Selection:

# Supported values: "dual" (default), "v4", "v6"
upstream:
  default:
    - 1.1.1.1
  ipVersion: dual

DNSSEC Configuration:

dnssec:
  enabled: true
  # Trust anchors from IANA root zone
  trustAnchors:
    - . IN DS 20326 8 2 E06D44B80B8F1D39A95C0B0D7C65D08458E880409BBC683457104237C7F8EC8D
  maxChainDepth: 10
  maxNSEC3Iterations: 150
  clockSkewToleranceSec: 3600

Client Groups:

clientGroups:
  default:
    upstream: default
    blocking: default
  kids:
    upstream: family-friendly
    blocking: strict
  iot:
    upstream: default
    blocking: none

clientLookup:
  # Map clients to groups by IP or subnet
  192.168.1.100-192.168.1.150: kids
  192.168.1.200: iot

Caching:

caching:
  minTime: 5m
  maxTime: 30m
  prefetching: true
  prefetchExpires: 2h
  prefetchThreshold: 5

Environment Variables

Blocky can be configured via environment variables:

# Override config file location
export BLOCKY_CONFIG_FILE=/etc/blocky/config.yml

# Enable debug logging
export LOG_LEVEL=debug

# Docker-specific
docker run -e LOG_LEVEL=debug spx01/blocky

4. Build & Run

Development Build

# Clone and setup
git clone https://github.com/0xERR0R/blocky.git
cd blocky

# Install dependencies
go mod download

# Run tests
make test

# Build for development
go build -o blocky ./cmd/blocky

# Run with local config
./blocky --config config.yml

Production Build

# Create optimized binary
make release

# Or build manually with optimizations
CGO_ENABLED=0 go build -ldflags="-s -w" -o blocky ./cmd/blocky

# Verify build
./blocky --version

Running as a Service

Systemd Service File (/etc/systemd/system/blocky.service):

[Unit]
Description=Blocky DNS Proxy
After=network.target

[Service]
Type=simple
User=blocky
Group=blocky
ExecStart=/usr/local/bin/blocky --config /etc/blocky/config.yml
Restart=always
RestartSec=5
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

Setup commands:

sudo useradd -r -s /usr/sbin/nologin blocky
sudo mkdir /etc/blocky
sudo cp config.yml /etc/blocky/
sudo cp blocky /usr/local/bin/
sudo systemctl daemon-reload
sudo systemctl start blocky
sudo systemctl enable blocky

5. Deployment

Docker Compose Deployment

version: '3.8'
services:
  blocky:
    image: spx01/blocky:latest
    container_name: blocky
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "4000:4000"
    volumes:
      - ./config.yml:/app/config.yml
      - ./logs:/logs
    environment:
      - TZ=UTC
    cap_add:
      - NET_BIND_SERVICE

Kubernetes Deployment (Helm)

# Add the Helm repository
helm repo add blocky https://0xerr0r.github.io/blocky-helm/
helm repo update

# Install Blocky
helm install blocky blocky/blocky \
  --namespace dns \
  --create-namespace \
  --values values.yaml

Sample values.yaml:

config:
  upstream:
    default:
      - 1.1.1.1
      - 8.8.8.8
  port: 53
  httpPort: 4000

service:
  type: LoadBalancer
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: nlb

resources:
  requests:
    memory: "64Mi"
    cpu: "100m"
  limits:
    memory: "128Mi"
    cpu: "200m"

Raspberry Pi Deployment

# Use ARM64 Docker image
docker run --name blocky \
  -p 53:53/tcp -p 53:53/udp \
  -v /opt/blocky/config.yml:/app/config.yml \
  --restart unless-stopped \
  spx01/blocky:latest

# Or build directly on Pi
GOARCH=arm64 GOOS=linux go build -o blocky ./cmd/blocky

6. Troubleshooting

Common Issues and Solutions

1. Port 53 Permission Errors

# Linux: Run with CAP_NET_BIND_SERVICE capability
sudo setcap CAP_NET_BIND_SERVICE=+eip /usr/local/bin/blocky

# Or run as root (not recommended)
sudo ./blocky --config config.yml

# Docker: Add capability
docker run --cap-add=NET_BIND_SERVICE spx01/blocky

2. DNSSEC Validation Failures

  • Check system time synchronization: date
  • Increase clock skew tolerance in config: 
    dnssec:
  clockSkewToleranceSec: 7200
  • Disable DNSSEC temporarily for debugging: 
    dnssec:
  enabled: false

3. Blocking Not Working

  • Check blocking status via API: curl http://localhost:4000/api/blocking/status
  • Enable blocking: curl http://localhost:4000/api/blocking/enable
  • Refresh lists: curl -X POST http://localhost:4000/api/lists/refresh
  • Verify client IP mapping in groups

4. High Memory Usage

  • Reduce cache size: 
    caching:
  maxTime: 15m
  maxItemsCount: 10000
  • Limit concurrent queries: 
    queryLog:
  concurrentQueries: 100

5. DNS Resolution Slow

  • Enable prefetching: 
    caching:
  prefetching: true
  prefetchThreshold: 3
  • Use multiple upstream resolvers
  • Check upstream resolver response times via Prometheus metrics

6. API Endpoints Not Accessible

  • Verify HTTP port is exposed: netstat -tulpn | grep :4000
  • Check firewall rules
  • Ensure CORS is configured if accessing from different origin

7. Logging Issues

  • Enable debug logging: 
    log:
  level: debug
  format: text
  timestamp: true
  • Check log file permissions
  • Verify database connection if using external logging

Diagnostic Commands

# Test DNS resolution
dig @localhost example.com

# Check Blocky health
curl http://localhost:4000/api/blocking/status

# Flush cache
curl -X POST http://localhost:4000/api/cache/flush

# View metrics
curl http://localhost:4000/metrics

# Check logs
docker logs blocky
journalctl -u blocky -f

Getting Help

  • Check documentation: https://0xERR0R.github.io/blocky/
  • View logs with LOG_LEVEL=debug
  • Enable Prometheus metrics for monitoring
  • Use the REST API for runtime configuration
  • File issues on GitHub with debug logs and configuration
← Project overviewView alternatives to blocky →