Installation

Get blockasaurus running on your system

Download

Download the latest release binary for your platform from the GitHub Releases page. Binaries are available for Linux (amd64, arm64, armv7), macOS, and Windows.

Configuration File

Create a minimal configuration file. Blockasaurus stores most of its configuration (upstreams, blocklists, client groups) in a SQLite database managed through the web UI. The YAML config file only needs a few basics:

/etc/blockasaurus/config.yml

# Blockasaurus configuration
databasePath: /var/lib/blockasaurus/blockasaurus.db

ports:
  dns: 53
  http: 4000

log:
  level: info

Run with systemd (Recommended)

Copy the binary and configuration into place, then install the systemd service:

# Install the binary
sudo cp blockasaurus /usr/bin/blockasaurus
sudo chmod 755 /usr/bin/blockasaurus

# Allow binding to privileged ports (53, 853)
sudo setcap 'cap_net_bind_service=+ep' /usr/bin/blockasaurus

# Create config and data directories
sudo mkdir -p /etc/blockasaurus /var/lib/blockasaurus

# Copy your config
sudo cp config.yml /etc/blockasaurus/config.yml

Install the systemd unit file:

/etc/systemd/system/blockasaurus.service

[Unit]
Description=Blockasaurus DNS proxy and ad-blocker
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/blockasaurus serve --config /etc/blockasaurus/config.yml
Restart=on-failure
RestartSec=5

DynamicUser=yes
StateDirectory=blockasaurus
Environment=BLOCKY_CONFIG_FILE=/etc/blockasaurus/config.yml

# Allow binding to privileged ports
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

# Filesystem hardening
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/var/lib/blockasaurus
ReadOnlyPaths=/etc/blockasaurus

# Kernel hardening
ProtectKernelModules=yes
ProtectKernelTunables=yes
ProtectKernelLogs=yes
NoNewPrivileges=yes
MemoryDenyWriteExecute=yes

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable --now blockasaurus

The web UI will be available at http://<your-server-ip>:4000.

ⓘ

On first start, blockasaurus seeds the database with a default upstream group containing Cloudflare DNS (1.1.1.1 and 1.0.0.1). You can change this in the web UI.

Run Directly

For testing or quick setup, run the binary directly:

./blockasaurus serve --config config.yml

⚠

To bind to port 53 on Linux without running as root, you must set the CAP_NET_BIND_SERVICE capability on the binary:
sudo setcap 'cap_net_bind_service=+ep' ./blockasaurus

Container Image

The official image is published to GitHub Container Registry:

ghcr.io/chrissnell/blockasaurus:latest

Docker Run

docker run -d \
  --name blockasaurus \
  --restart unless-stopped \
  -p 53:53/udp \
  -p 53:53/tcp \
  -p 4000:4000/tcp \
  -v /path/to/config.yml:/app/config.yml:ro \
  -v blockasaurus-data:/data \
  ghcr.io/chrissnell/blockasaurus:latest

Docker Compose

docker-compose.yml

services:
  blockasaurus:
    image: ghcr.io/chrissnell/blockasaurus:latest
    container_name: blockasaurus
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "4000:4000/tcp"
    volumes:
      - ./config.yml:/app/config.yml:ro
      - blockasaurus-data:/data

volumes:
  blockasaurus-data:

docker compose up -d

ⓘ

The container runs as UID 100 (non-root) with a read-only root filesystem. The /data volume stores the SQLite configuration database.

Prerequisites

Kubernetes cluster (1.24+)
Helm 3
A LoadBalancer provider (MetalLB, cloud LB, etc.) for exposing DNS
Optional: cert-manager for automatic TLS certificates

Install the Chart

# Add the chart (or use the local chart from the repo)
helm install blockasaurus ./packaging/helm/blockasaurus \
  --namespace blockasaurus \
  --create-namespace \
  -f values.yaml

Minimal values.yaml

values.yaml

config:
  ports:
    dns: 53
    http: 80
  databasePath: /data/blocky.db

persistence:
  enabled: true
  size: 256Mi

service:
  dns:
    enabled: true
    type: LoadBalancer

This gives you plain DNS on port 53 via a LoadBalancer IP, with the web UI accessible via the ClusterIP HTTP service on port 80.

Exposing the Web UI

To access the web UI, either:

Port-forward: kubectl port-forward svc/blockasaurus 4000:80 -n blockasaurus
Ingress: Enable the ingress section in values.yaml
LoadBalancer: Set service.dns.http: true to expose HTTP on the DNS LoadBalancer

✓

For TLS setups (DoH, DoT), see the TLS Configuration page. The Helm chart integrates with cert-manager to automatically provision certificates.

Key Helm Values

Value	Description	Default
`config.ports.dns`	DNS listen port	`53`
`config.ports.http`	HTTP (web UI + DoH) port	`80`
`config.databasePath`	SQLite config database path	`/data/blocky.db`
`persistence.enabled`	Enable PVC for database	`true`
`service.dns.type`	DNS service type	`LoadBalancer`
`service.dns.loadBalancerIP`	Fixed LB IP (MetalLB)	empty
`tls.enabled`	Mount TLS certs for DoT/DoH	`false`
`certificate.enabled`	Create cert-manager Certificate	`false`

Requirements

Go 1.26+
Node.js 22+ and npm (for the web UI)
GNU Make

Build

# Clone the repository
git clone https://github.com/chrissnell/blockasaurus.git
cd blockasaurus

# Build the web UI
cd web/ui
npm install
npx vite build
cd ../..

# Build the Go binary
make build

The binary is written to bin/blockasaurus.

Build the Docker Image

docker buildx build -t blockasaurus:local .

The multi-stage Dockerfile handles both the UI build (Node) and Go compilation. The final image is based on scratch — no shell, no OS packages, just the binary.

Makefile Targets

Target	Description
`make build`	Build the binary
`make test`	Run unit tests
`make lint`	Run linter
`make docker-build`	Build Docker image
`make e2e-test`	Run end-to-end tests