AdGuard Home with Docker - Part 3: Installation & Configuration

January 21, 2026 · 10 min. · networking ,privacy ,docker ,tutorial ,adguard ,raspberry-pi

In this part, we’ll deploy AdGuard Home using Docker, complete the initial setup wizard, and configure your network to use it for DNS.

Table of Contents

  1. Installing AdGuard Home
  2. Initial Configuration
  3. Recommended Defaults
  4. Configuring Your Devices

Installing AdGuard Home

Understanding AdGuard Home Ports

AdGuard Home requires several ports to function. Here’s what you need to know:

Required Ports:

Why Port 53 Can’t Be Changed: DNS operates on port 53 by internet standards. Devices expect DNS to be on port 53, so changing it would break DNS resolution for all your devices.

Common Port Conflicts:

Method 1: Using Docker Run (Simplest)

This is the quickest way to get started:

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

What this command does:

Docker Compose makes it easier to manage and update your container using a configuration file.

Step 1: Install Docker Compose

Copy and paste this command:

sudo apt install docker-compose -y

Step 2: Create a Folder for AdGuard Home

These commands create a new folder with appropriate permissions:

mkdir -p ~/adguardhome
cd ~/adguardhome
mkdir -p -m 700 work
mkdir -p -m 700 conf

What this does:

Step 3: Create a Configuration File

Now we’ll create a file called docker-compose.yml. This file tells Docker how to run AdGuard Home.

Type this command:

vim docker-compose.yml

Vim will open. Press i to enter insert mode, then copy and paste this entire block:

services:
  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    restart: unless-stopped
    ports:
      - '53:53/tcp'
      - '53:53/udp'
      - '80:80/tcp'
      - '443:443/tcp'
      - '443:443/udp'
      - '3000:3000/tcp'
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf

Now save the file:

  1. Press Esc to exit insert mode
  2. Type :wq and press Enter

Success! You’ve created your configuration file.

Alternative: Custom Ports (Optional - Only if you have port conflicts)

Skip this section if: Ports 80 and 3000 are free on your system.

Use this section if: You get errors like “port already in use” or you’re running other services (web servers, other containers, etc.).

When Do You Need Custom Ports?

You need custom ports if:

How to Use Custom Ports

Instead of the docker-compose.yml above, use this version with custom ports:

Open your docker-compose.yml file again:

vim docker-compose.yml

Replace the content with this:

Press i to enter insert mode, delete the existing content, and paste this:

services:
  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    restart: unless-stopped
    ports:
      - '53:53/tcp' # DNS - Must stay on port 53
      - '53:53/udp' # DNS - Must stay on port 53
      - '8080:80/tcp' # Web UI - Changed from 80 to 8080
      - '3001:3000/tcp' # Setup wizard - Changed from 3000 to 3001
      - '8443:443/tcp' # HTTPS (optional)
      - '8443:443/udp' # DNS-over-HTTPS (optional)
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf

Then press Esc and type :wq to save.

Understanding Port Mapping:

The format is: "HOST_PORT:CONTAINER_PORT"

Examples:

Important Notes:

⚠️ Port 53 CANNOT be changed - DNS must use port 53, or devices won’t be able to use it

Accessing AdGuard Home with Custom Ports

With default ports:

With custom ports (like example above):

Example with real IP:

Setup: http://192.168.1.100:3001
Dashboard: http://192.168.1.100:8080
Common Port Alternatives

If ports are taken, here are good alternatives:

ServiceDefault PortAlternativeUsage
Web UI808080, 8888, 8081Dashboard
Setup Wizard30003001, 3002, 8000Initial setup
HTTPS4438443, 4443Secure web
Checking if a Port is Already in Use

Before starting, check if ports are free:

# Check if port 80 is in use
sudo lsof -i :80

# Check if port 3000 is in use
sudo lsof -i :3000

Or check all ports at once:

sudo netstat -tulpn | grep -E ':(80|3000|53) '
Saving Your Custom Configuration

After editing:

  1. Press Ctrl+X
  2. Press Y to save
  3. Press Enter to confirm

Step 4: Start AdGuard Home

Now let’s start AdGuard Home! Run this command:

docker-compose up -d

What this does: Starts AdGuard Home in the background. The -d means “detached mode” (runs in background).

You’ll see Docker downloading and starting everything. This takes 1-2 minutes.

Verifying Installation

Let’s check if AdGuard Home is running. Type:

docker ps

What to look for: You should see a line with adguardhome in it. If you do, congratulations! It’s running!

Initial Configuration

Step 1: Access the Web Interface

Now we’ll set up AdGuard Home using a web browser!

  1. Find your device’s IP address:

    In the terminal, type:

    hostname -I

    You’ll see something like: 192.168.1.100

    Write this number down! This is your device’s address on your network.

  2. Open a web browser

    • You can use any device on the same WiFi/network (phone, tablet, computer)
    • Open Chrome, Firefox, Safari, or any browser

  3. Type in the address bar:

    Type: http://YOUR_DEVICE_IP:3000

    Example: If your IP was 192.168.1.100, type: http://192.168.1.100:3000

    Press Enter.

Tip: If it doesn’t load, make sure:

Step 2: Setup Wizard

You’ll see the AdGuard Home setup wizard:

  1. Welcome Screen: Click “Get Started”

  2. Admin Web Interface Setup:

    • Choose port 80 (or keep 3000 if you prefer)
    • Click “Next”

  3. DNS Server Setup:

    • Keep port 53 (default)
    • Click “Next”

  4. Create Admin Account:

    • Username: Choose your admin username
    • Password: Create a strong password
    • Click “Next”

  5. Configuration Complete: Click “Open Dashboard”

Step 3: Login

Use the credentials you just created to log in.

After completing the initial setup wizard, here are the recommended settings for most users:

Upstream DNS Servers

What to use: Choose one privacy-focused option

Where: Settings → DNS settings → Upstream DNS servers

Why these? Both are privacy-focused, fast, and reliable. Cloudflare is slightly faster, Quad9 includes malware blocking.

Blocklists

Start with these two (don’t over-subscribe):

  1. AdGuard DNS filter (pre-installed) - General ad blocking

    • Already enabled by default

  2. OISD Big List - Comprehensive, well-maintained list

    • Add via: Filters → DNS blocklists → Add blocklist
    • URL: https://big.oisd.nl/

Why only 2? More lists = slower DNS lookups. These two cover 95% of ads and trackers. You can always add more later if needed.

Query Logging

Recommended setting: 24-hour retention

Where: Settings → DNS settings → Query log retention

Why 24 hours?

Privacy note: Logs stay on your device, never leave your network.

Interface Settings

That’s it! These defaults work well for most home networks. You can always adjust later as you learn more about what works for your setup.

Configuring Your Devices

Now that AdGuard Home is running with recommended settings, you need to configure your devices to use it.

This applies AdGuard Home to ALL devices on your network automatically.

Note: Every router is different! The exact steps vary by manufacturer and model.

General Steps:

  1. Access your router’s admin panel

    • Usually: 192.168.1.1, 192.168.0.1, or 192.168.1.254
    • Or check the sticker on your router
    • Enter username/password (often on router sticker)

  2. Find DNS settings

    • Look in these sections (varies by router):
      • “DHCP Settings” or “DHCP Server”
      • “LAN Settings”
      • “Internet Settings”
      • “Network Settings”
      • “Advanced” → “DNS”

  3. Change Primary DNS

    • Enter your AdGuard Home IP address (the one you found earlier)
    • Example: 192.168.1.100

  4. Secondary DNS (optional)

    • Best practice: Leave blank
    • Alternative: Use a backup DNS like 1.1.1.1 (Cloudflare) or 8.8.8.8 (Google)
    • Warning: If you set a secondary, devices may bypass AdGuard Home when the primary is slow

  5. Save and Reboot

    • Save settings
    • Reboot your router (some routers do this automatically)

Finding Router-Specific Instructions:

Can’t find DNS settings? Search Google for:

Examples:

Mesh Systems:

Option 2: Configure Individual Devices

If you can’t configure your router or want to test on specific devices first:

On Windows:

  1. Settings → Network & Internet → Change adapter options
  2. Right-click your connection → Properties
  3. Select “Internet Protocol Version 4 (TCP/IPv4)” → Properties
  4. Select “Use the following DNS server addresses”
  5. Preferred DNS: Your AdGuard Home IP (e.g., 192.168.1.100)
  6. Click OK

On macOS:

  1. System Preferences → Network
  2. Select your connection → Advanced → DNS
  3. Click “+” and add your AdGuard Home IP
  4. Click OK and Apply

On iOS/Android:

  1. Settings → WiFi
  2. Tap your network
  3. Configure DNS → Manual
  4. Add your AdGuard Home IP
  5. Save

Testing Your Setup

After configuring your router or devices, let’s verify everything is working:

Test 1: Check Query Log

  1. Open AdGuard Home dashboard: http://YOUR_IP
  2. Go to “Query Log”
  3. Browse a website on your phone or computer
  4. You should see DNS queries appearing in real-time

If you don’t see queries: Your devices aren’t using AdGuard Home. Double-check your router/device DNS settings.

Test 2: Visit an Ad-Heavy Website

  1. Visit a site known for ads (news sites, blogs, etc.)
  2. Ads should be blocked
  3. Check the AdGuard Home dashboard - you should see blocked queries

Test 3: Test Ad Blocking

Visit: https://canyoublockit.com/

This site tests if your ad blocker is working. You should see mostly green checkmarks.

Next Steps

Your AdGuard Home is now protecting your entire network! In Part 4, we’ll explore advanced features, learn about maintenance, and troubleshoot common issues.

Continue to Part 4: Advanced Features & Maintenance →

Series Navigation: ← Part 2: System Setup | Part 3 of 4 | Next: Advanced Features →