# AdGuard Home with DoH/DoT

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

- Category: Home Lab & Self-Hosting
- Difficulty: intermediate
- Components: adguard-home, nginx, prometheus, grafana
- Tags: dns, ad-blocking, adguard, doh, dot, privacy
- Source: https://docker.recipes/homelab/adguard-home-stack

## 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.

## 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

## Use cases

- Homelab DNS infrastructure with privacy protection and comprehensive monitoring
- Small office networks requiring centralized ad blocking and content filtering
- IoT device networks where individual ad blocking installation is impossible
- Privacy-focused households wanting to prevent DNS tracking and profiling
- Educational environments needing parental controls and safe browsing enforcement
- Network administrators requiring detailed DNS analytics and threat intelligence
- Remote 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

## docker-compose.yml

```yaml
services:
  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:
    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:
    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

volumes:
  adguard_work:
  adguard_conf:
  prometheus_data:
  grafana_data:

networks:
  adguard-net:
    driver: bridge
```

## .env

```bash
# Grafana
GRAFANA_PASSWORD=secure_grafana_password

# AdGuard Home default credentials
# Username: admin
# Password: Set during initial setup
```

## Usage notes

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

## 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

