AdGuard Home with Docker - Part 1: Introduction & Prerequisites

January 19, 2026 · 11 min. · networking ,privacy ,docker ,tutorial ,adguard ,raspberry-pi

A few months ago, I got tired of seeing ads on every device in my home network. Not just the obvious banner ads, but trackers, analytics scripts, and all the invisible data collection happening in the background.

I knew about Pi-hole and AdGuard Home - network-wide ad blockers that work at the DNS level. But every guide I found assumed you already knew what you were doing. They’d throw commands at you without explaining what they meant, skip over crucial details, or assume you had everything configured just right.

So I decided to write the guide I wish I’d had when I started. This is a complete series - everything you need in one place.

TL;DR / Quick Start

If you’re experienced with Linux and Docker, here’s the 5-minute version:

  1. Hardware: Raspberry Pi 4 (2GB+) or any Linux machine
  2. OS: Raspberry Pi OS Lite (64-bit) recommended
  3. Install Docker: curl -fsSL https://get.docker.com | sh
  4. Set Static IP: Configure DHCP reservation on your router
  5. Deploy AdGuard Home:
    mkdir -p ~/adguardhome && cd ~/adguardhome
# Create docker-compose.yml (see Part 3)
docker-compose up -d
  6. Configure: Access http://YOUR_IP:3000 and complete setup wizard
  7. Update Router DNS: Point your router’s primary DNS to your AdGuard Home IP

New to this? Follow the detailed guide below - we explain everything step by step.

Table of Contents

  1. Why Network-Level Ad Blocking?
  2. AdGuard Home vs Pi-hole
  3. Why Docker?
  4. Prerequisites - What You’ll Need
  5. Quick Reference: Keyboard Shortcuts
  6. Text Editor Quick Reference

Why Network-Level Ad Blocking?

Here’s the thing: browser extensions are great, but they only work on that specific browser on that specific device. What about:

AdGuard Home solves all of this by blocking ads and trackers at the network level - before they even reach your devices.

AdGuard Home vs Pi-hole

I used Pi-hole for months before switching to AdGuard Home. Here’s what I discovered:

Why AdGuard Home Won Me Over

  1. Simpler Setup

    • Pi-hole: Complex web installer, dependency management, manual DNS configuration
    • AdGuard Home: Single Docker container, web-based setup wizard, done in 5 minutes

  2. Modern Interface

    • Pi-hole: Functional but dated UI, slower response times
    • AdGuard Home: Clean, responsive dashboard with real-time stats

  3. Built-in HTTPS/DNS-over-HTTPS

    • Pi-hole: Requires additional setup, manual certificate management
    • AdGuard Home: Native support, easy Let’s Encrypt integration

  4. Better Filtering Options

    • Pi-hole: Basic blocklists, regex support requires learning their syntax
    • AdGuard Home: Advanced filtering rules, supports AdBlock-style syntax, parental controls built-in

  5. Easier Updates

    • Pi-hole: Multi-step update process, sometimes breaks
    • AdGuard Home: Pull new Docker image, restart - takes 30 seconds

  6. Query Log Search

    • Pi-hole: Limited search functionality
    • AdGuard Home: Powerful filtering, export options, better analytics

What Pi-hole Does Better

Bottom Line

For this tutorial, I’m focusing on AdGuard Home because it offers a modern interface and simpler Docker-based setup. Pi-hole is a solid, well-established option with a larger community—both are excellent choices for network-wide ad blocking.

Choose AdGuard Home if: You want the easiest setup, modern UI, and built-in HTTPS/DoH support.

Choose Pi-hole if: You prefer a mature ecosystem with extensive third-party integrations.

Why Docker?

You might wonder: “Why not just install AdGuard Home directly?”

Docker makes everything easier:

Think of Docker like an app on your phone - you install it, it works, you can remove it cleanly. Direct installation is messy and complicated.

Real-World Example:

Prerequisites (What You’ll Need)

Why Do I Need a Dedicated Device?

Important: AdGuard Home needs to run 24/7 to protect your network. Here’s why:

Think of it like your WiFi router - it needs to be on all the time for your internet to work.

Hardware Requirements (Your Device)

  1. Raspberry Pi ⭐ BEST CHOICE

    • Models: Pi 4 (4GB or 8GB), Pi 5, or Pi 3B+
    • Cost: $35-75
    • Power: Uses only 2-8 watts
    • Size: Credit card sized
    • Perfect for: 24/7 operation, low energy use

  2. Mini PC / Thin Client

    • Examples: Intel NUC, HP/Dell Thin Clients, Lenovo ThinkCentre Tiny
    • Cost: $50-150 (used), $200+ (new)
    • Power: 10-25 watts
    • Perfect for: More power, better performance, can run other services too

  3. Old Laptop

    • Minimum: 2GB RAM, any CPU from last 10 years
    • Cost: Free (if you have one)
    • Power: 15-45 watts
    • Consider: Remove battery if always plugged in (prevents battery swelling)
    • Perfect for: Reusing old hardware, built-in screen for troubleshooting

  4. Old Desktop PC

    • Minimum: 2GB RAM, any CPU
    • Cost: Free (if you have one)
    • Power: 50-150 watts (⚠️ higher electricity costs)
    • Only if: You don’t have other options
    • Consider: May cost $50-100/year in electricity

  5. Orange Pi / Other SBCs (Single Board Computers)

    • Similar to Raspberry Pi
    • Often cheaper but less community support
    • Good alternative if Raspberry Pi unavailable

What You’ll Also Need

Essential:

Highly Recommended (Optional - Can be skipped by experienced users):

Optional (But Convenient):

Headless Operation (No Screen Needed) 💡 RECOMMENDED

Optional - Experienced users can skim this section

What is “headless”? Running your device without a monitor, keyboard, or mouse.

Why go headless?

  1. Cost Savings

    • Don’t need to buy a monitor, keyboard, or mouse
    • Raspberry Pi can run “headless” right out of the box

  2. Space Savings

    • Device can sit next to your router
    • No desk space needed

  3. Energy Savings

    • Monitors use 20-40 watts
    • No monitor = lower electricity bill

  4. Professional Setup

    • Servers run headless - this is how professionals do it
    • More reliable (fewer components to fail)

How to manage headless device:

Option 1: SSH (Secure Shell) - BEST METHOD ⭐

Option 2: Plug in When Needed

Recommendation:

For this tutorial:

Software Requirements

For Raspberry Pi

Download Raspberry Pi OS:

Which Version Should You Download?

You have three main options:

  1. Raspberry Pi OS Lite (64-bit) ⭐ RECOMMENDED FOR THIS PROJECT

    • Best for: Headless operation (no monitor)
    • Size: Smallest (~400MB)
    • No desktop environment - Perfect for servers running 24/7
    • Recommended for: Pi 3B+, Pi 4, Pi 5 with 2GB+ RAM
    • Why choose this: Less RAM usage, faster performance, perfect for AdGuard Home

  2. Raspberry Pi OS with Desktop (64-bit)

    • Best for: If you want a graphical interface
    • Size: Medium (~1GB)
    • Includes: Desktop environment, basic apps
    • Recommended for: Pi 4, Pi 5 with 4GB+ RAM
    • Why choose this: Easier to troubleshoot with visual interface, good for beginners

  3. Raspberry Pi OS Full (64-bit)

    • Best for: Using Pi as a desktop computer
    • Size: Large (~2.5GB)
    • Includes: Desktop + recommended software
    • Not recommended: Too much overhead for a server

32-bit vs 64-bit:

How to Install:

  1. Download Raspberry Pi Imager from https://www.raspberrypi.com/software/

  2. Insert your microSD card into your computer

  3. Open Raspberry Pi Imager

  4. Choose Device: Select your Raspberry Pi model

    Select Raspberry Pi device

  5. Choose OS: Raspberry Pi OS Lite (64-bit)

    Select operating system

  6. Choose Storage: Select your microSD card

    Select storage

  7. Customization Settings: After selecting device, OS, and storage, the customization menu will automatically open. This is where you’ll configure:

    Hostname: Set a name for your Pi (e.g., pilab)

    Configure hostname

    Localisation: Configure your timezone and keyboard layout

    Configure localisation

    User: Create your username and password

    Configure user

    WiFi: Configure your WiFi network (if not using ethernet)

    Configure WiFi

    SSH: Enable SSH (very important for headless!)

    Enable SSH

    Raspberry Pi Connect: Optionally enable Pi Connect (can be skipped)

    Raspberry Pi Connect

  8. Review and Write: Review your configuration

    Review configuration

  9. Confirm: Confirm that you want to overwrite the SD card (this will erase all data!)

    Confirm write

  10. Writing Process: Wait for the writing process to complete

    Writing progress

  11. Complete!: Once you see “Write complete”, you can safely eject your SD card

    Write complete

Pro Tip: The Raspberry Pi Imager can configure SSH and WiFi for you during the installation process - this saves you time!

For Old Laptop/Desktop

Internet Connection

Network Setup: Where to Connect Your Device

AdGuard Home can work with any network setup:

Option 2: Mesh Network Connection

Option 3: Network Switch Connection

Option 4: WiFi Connection

Important Network Notes:

⚠️ Router Configuration Varies by Brand

⚠️ Mesh System DNS Configuration

⚠️ ISP Router/Modem Combos

Bottom Line: As long as your AdGuard Home device can connect to your network and you can access your router settings to change DNS, you’re good to go!

Quick Reference: Essential Keyboard Shortcuts

Terminal Shortcuts

New to command line? Don’t worry! Each command is explained in simple terms.

Text Editor Quick Reference

This tutorial uses vim as the command-line text editor to edit configuration files. Here are the essentials:

Installing Vim

First, install vim if you don’t have it:

sudo apt update && sudo apt install vim -y

Using Vim

Open a file:

vim filename.txt

Vim has two modes:

Essential commands:

To Do ThisPress
Start typingi (enters Insert mode)
Stop typingEsc (back to Normal mode)
Save and quitEsc, then type :wq and press Enter
Quit without savingEsc, then type :q! and press Enter
Undou (in Normal mode)

If you get stuck in Vim:

  1. Press Esc several times
  2. Type :q! and press Enter

Paste text: Press i to enter Insert mode, then right-click or Ctrl+Shift+V

Copy and Paste in Terminal

Note: Regular Ctrl+C and Ctrl+V don’t work in terminal!

Next Steps

Now that you understand the prerequisites and have your hardware ready, continue to Part 2 where we’ll set up SSH, install Docker, and configure a static IP address.

Continue to Part 2: System Setup →

Series Navigation: Part 1 of 4 | Next: System Setup →