AdGuard Home with DoH/DoT

intermediate

Privacy-focused ad blocking with AdGuard Home, DNS-over-HTTPS, and DNS-over-TLS support.

Overview

AdGuard Home is a network-wide DNS sinkhole that blocks advertisements and trackers at the DNS level, developed by AdGuard as an open-source alternative to commercial DNS filtering services. Unlike browser-based ad blockers, AdGuard Home protects all devices on your network by intercepting DNS queries before they reach advertising servers, while supporting modern encrypted DNS protocols including DNS-over-HTTPS (DoH), DNS-over-TLS (DoT), and DNS-over-QUIC. This stack combines AdGuard Home with Prometheus and Grafana to create a comprehensive privacy-focused DNS infrastructure with advanced monitoring capabilities. Prometheus scrapes metrics from AdGuard Home's built-in statistics API, while Grafana visualizes query patterns, blocking rates, and client behavior through customizable dashboards. The configuration enables both traditional DNS (port 53) and encrypted DNS protocols (ports 443 and 853) to protect against DNS eavesdropping and manipulation. This setup is ideal for privacy-conscious homelab enthusiasts, small businesses wanting to protect their networks from tracking, and IT administrators who need detailed insights into DNS traffic patterns. The combination of ad blocking, encrypted DNS, and comprehensive monitoring makes this stack particularly valuable for environments where both privacy and visibility are critical requirements.

Key Features

DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) support for encrypted DNS queries
Network-wide ad and tracker blocking using customizable filter lists
Built-in DHCP server for automatic DNS configuration across network devices
Parental controls with safe search enforcement and content filtering
Real-time DNS query logging with client identification and response time tracking
Prometheus metrics integration for advanced analytics and alerting
Grafana dashboards for visualizing DNS traffic patterns and blocking statistics
Custom DNS rewrites and upstream DNS server configuration with load balancing

Common Use Cases

1Homelab DNS infrastructure with privacy protection and comprehensive monitoring
2Small office networks requiring centralized ad blocking and content filtering
3IoT device networks where individual ad blocking installation is impossible
4Privacy-focused households wanting to prevent DNS tracking and profiling
5Educational environments needing parental controls and safe browsing enforcement
6Network administrators requiring detailed DNS analytics and threat intelligence
7Remote work setups where secure DNS resolution protects against malicious domains

Prerequisites

Docker host with at least 512MB RAM available for the complete stack
Network administrator access to configure router DNS settings or DHCP
SSL certificates for DoH/DoT functionality (can be self-signed for internal use)
Understanding of DNS concepts and network routing for proper upstream configuration
Port 53 availability on Docker host (may conflict with systemd-resolved)
Basic knowledge of Prometheus metrics and Grafana dashboard configuration

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  adguardhome: 
3    image: adguard/adguardhome:latest
4    ports: 
5      - "53:53/tcp"
6      - "53:53/udp"
7      - "67:67/udp"
8      - "853:853/tcp"
9      - "3000:3000/tcp"
10      - "443:443/tcp"
11      - "443:443/udp"
12    volumes: 
13      - adguard_work:/opt/adguardhome/work
14      - adguard_conf:/opt/adguardhome/conf
15      - ./certs:/opt/adguardhome/certs:ro
16    networks: 
17      - adguard-net
18    restart: unless-stopped
19
20  prometheus: 
21    image: prom/prometheus:latest
22    ports: 
23      - "9090:9090"
24    volumes: 
25      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
26      - prometheus_data:/prometheus
27    networks: 
28      - adguard-net
29    restart: unless-stopped
30
31  grafana: 
32    image: grafana/grafana:latest
33    ports: 
34      - "3001:3000"
35    environment: 
36      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
37    volumes: 
38      - grafana_data:/var/lib/grafana
39    depends_on: 
40      - prometheus
41    networks: 
42      - adguard-net
43    restart: unless-stopped
44
45volumes: 
46  adguard_work: 
47  adguard_conf: 
48  prometheus_data: 
49  grafana_data: 
50
51networks: 
52  adguard-net: 
53    driver: bridge

.env Template

.env

1# Grafana
2GRAFANA_PASSWORD=secure_grafana_password
3
4# AdGuard Home default credentials
5# Username: admin
6# Password: Set during initial setup

Usage Notes

1Initial setup at http://localhost:3000
2Supports DoH (port 443) and DoT (port 853)
3Configure upstream DNS servers in settings
4Enable DHCP server for automatic DNS configuration

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

adguardhome

adguardhome:
  image: adguard/adguardhome:latest
  ports:
    - 53:53/tcp
    - 53:53/udp
    - 67:67/udp
    - 853:853/tcp
    - 3000:3000/tcp
    - 443:443/tcp
    - 443:443/udp
  volumes:
    - adguard_work:/opt/adguardhome/work
    - adguard_conf:/opt/adguardhome/conf
    - ./certs:/opt/adguardhome/certs:ro
  networks:
    - adguard-net
  restart: unless-stopped

prometheus

prometheus:
  image: prom/prometheus:latest
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    - prometheus_data:/prometheus
  networks:
    - adguard-net
  restart: unless-stopped

grafana

grafana:
  image: grafana/grafana:latest
  ports:
    - "3001:3000"
  environment:
    GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
  volumes:
    - grafana_data:/var/lib/grafana
  depends_on:
    - prometheus
  networks:
    - adguard-net
  restart: unless-stopped

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  adguardhome:
5    image: adguard/adguardhome:latest
6    ports:
7      - "53:53/tcp"
8      - "53:53/udp"
9      - "67:67/udp"
10      - "853:853/tcp"
11      - "3000:3000/tcp"
12      - "443:443/tcp"
13      - "443:443/udp"
14    volumes:
15      - adguard_work:/opt/adguardhome/work
16      - adguard_conf:/opt/adguardhome/conf
17      - ./certs:/opt/adguardhome/certs:ro
18    networks:
19      - adguard-net
20    restart: unless-stopped
21
22  prometheus:
23    image: prom/prometheus:latest
24    ports:
25      - "9090:9090"
26    volumes:
27      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
28      - prometheus_data:/prometheus
29    networks:
30      - adguard-net
31    restart: unless-stopped
32
33  grafana:
34    image: grafana/grafana:latest
35    ports:
36      - "3001:3000"
37    environment:
38      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
39    volumes:
40      - grafana_data:/var/lib/grafana
41    depends_on:
42      - prometheus
43    networks:
44      - adguard-net
45    restart: unless-stopped
46
47volumes:
48  adguard_work:
49  adguard_conf:
50  prometheus_data:
51  grafana_data:
52
53networks:
54  adguard-net:
55    driver: bridge
56EOF
57
58# 2. Create the .env file
59cat > .env << 'EOF'
60# Grafana
61GRAFANA_PASSWORD=secure_grafana_password
62
63# AdGuard Home default credentials
64# Username: admin
65# Password: Set during initial setup
66EOF
67
68# 3. Start the services
69docker compose up -d
70
71# 4. View logs
72docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/adguard-home-stack/run | bash

Troubleshooting

AdGuard Home web interface shows 'bind: address already in use': Stop systemd-resolved with 'sudo systemctl disable systemd-resolved' and configure alternative DNS resolution
DoH/DoT not working with certificate errors: Ensure SSL certificates in ./certs directory match your domain name and have proper file permissions (644)
Grafana shows 'no data points' for AdGuard metrics: Verify prometheus.yml includes AdGuard Home target at 'adguardhome:3000/control/stats' endpoint
DNS queries not being blocked on client devices: Check that devices are configured to use the Docker host IP as their DNS server
High memory usage by Prometheus: Reduce metrics retention time in prometheus.yml or limit the query log retention in AdGuard Home settings
AdGuard Home loses configuration after restart: Ensure adguard_conf volume is properly mounted and has write permissions for container user

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

adguard-homenginxprometheusgrafana

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download