Installing AdGuard Home on Debian/Ubuntu (Docker)

🧠 What is AdGuard Home?

AdGuard Home is a network-wide 💻 DNS-based ad blocker 🚫📰 and tracker blocker 🕵️‍♂️. It acts as your local DNS server, filtering ads, trackers, and malicious domains 🔐 for all devices on your network 🛜.

🐳 Installing AdGuard Home on Debian/Ubuntu (Docker)

⚙️ Step 1: Install Docker

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io
sudo systemctl enable --now docker

📌 This installs Docker and ensures it starts automatically.

📁 Step 2: Create AdGuard Data Directories

sudo mkdir -p /opt/adguardhome/work /opt/adguardhome/conf /opt/adguardhome/certs

🗂 These directories store AdGuard’s config, data, and SSL certs.

🧩 Step 3: Start AdGuard Home Container

sudo docker run -d \
  --name adguardhome \
  --restart unless-stopped \
  -v /opt/adguardhome/work:/opt/adguardhome/work \
  -v /opt/adguardhome/conf:/opt/adguardhome/conf \
  -v /opt/adguardhome/certs:/opt/adguardhome/certs \
  -p 53:53/tcp -p 53:53/udp \
  -p 67:67/udp -p 68:68/udp \
  -p 80:80/tcp -p 443:443/tcp \
  -p 3000:3000/tcp \
  adguard/adguardhome:latest

🔌 Port 3000 is for the initial setup UI.

🌐 Step 4: Initial Web Setup

🌍 Visit: http://<your-server-ip>:3000
📋 Follow the on-screen wizard to configure your instance.

🔒 Step 5: Enable HTTPS with Custom SSL (Optional)

Place your SSL cert and key in:

/opt/adguardhome/certs/

Filenames must be:

tls.crt  – Your certificate 📜
tls.key  – Your private key 🔑

Edit AdGuardHome.yaml (in /opt/adguardhome/conf/) to include:

tls:
  enabled: true
  server_name: "<your-domain>"
  certificate_chain: "/opt/adguardhome/certs/tls.crt"
  private_key: "/opt/adguardhome/certs/tls.key"

Restart AdGuard:

docker restart adguardhome

✅ Now your AdGuard UI should be accessible at https://your-domain

🛠 Repair / Reinstall AdGuard with Docker

No need to reinstall your OS ⚠️ — here’s a clean recovery process.

💾 Step 1: Backup (If Config is Valuable)

docker stop adguardhome
docker rename adguardhome adguardhome_backup_$(date +%F-%T)

🔐 Save the contents of /opt/adguardhome/conf/ if needed.

🧹 Step 2: Remove Broken Installation

docker rm -f adguardhome
docker rmi adguard/adguardhome:latest
sudo rm -rf /opt/adguardhome

🧽 Clean slate.

🔄 Step 3: Fresh Reinstall

sudo mkdir -p /opt/adguardhome/work /opt/adguardhome/conf /opt/adguardhome/certs

sudo docker run -d \
  --name adguardhome \
  --restart unless-stopped \
  -v /opt/adguardhome/work:/opt/adguardhome/work \
  -v /opt/adguardhome/conf:/opt/adguardhome/conf \
  -v /opt/adguardhome/certs:/opt/adguardhome/certs \
  -p 53:53/tcp -p 53:53/udp \
  -p 67:67/udp -p 68:68/udp \
  -p 80:80/tcp -p 443:443/tcp \
  -p 3000:3000/tcp \
  adguard/adguardhome:latest

🔁 Step 4: Restore Configuration (Optional)

cp -r /root/old_data/allbackup/opt/adguardhome/* /opt/adguardhome/
docker restart adguardhome

📂 Bring back your settings if you had a backup.

🧠 Step 5: Improve DNS Speed (Optional)

In AdGuardHome.yaml:

bootstrap_dns:
  - 1.1.1.1
  - 8.8.8.8

upstream_dns:
  - https://dns.cloudflare.com/dns-query
  - https://dns.google/dns-query

Then restart:

docker restart adguardhome

🚀 Now AdGuard uses encrypted DNS-over-HTTPS.

🧪 Step 6: Test DNS

dig @127.0.0.1 google.com

🔍 Ensure DNS queries resolve correctly.

📱 Device DNS Configuration

🍎 iOS / macOS

Option 1: Automatic

Visit: https://your-domain/admin
Go to: Setup Guide → iOS/macOS
Download and install the MobileConfig profile.

🛡 DNS now flows through AdGuard automatically.

Option 2: Manual DNS

Settings → Wi-Fi → Your Network → Configure DNS → Manual
➕ Add: 192.168.1.X (your AdGuard IP)
➖ Remove other DNS servers

✅ Final Checks

✅ Web GUI loads at https://your-domain
✅ dig works via AdGuard
✅ DNS filtering active
✅ SSL active (if configured)
✅ Firewall unchanged (consider UFW rules)
✅ docker ps shows healthy AdGuard

📦 Bonus: Auto Backup Script (Optional)

#!/bin/bash
mkdir -p /root/adguard_backups
tar -czf /root/adguard_backups/adguard_conf_$(date +%F).tar.gz /opt/adguardhome/conf

Schedule it:

crontab -e

Add:

0 3 * * * /root/backup_adguard.sh

💡 Daily 3 AM config backups = peace of mind.