AdGuard Home Docker Compose: No Ads + Privacy in 5 min

AdGuard Home is a kick-ass network-wide ad blocker. This AdGuard Home Docker Compose guide shows you how to get started with AdGuard Home in minutes.

AdGuard Home (not to be confused with the myriads of other AdGuard products), is a DNS sinkhole that drops any connection requests to domains/hosts that are known ad servers and trackers.

This worthy Pi-Hole alternative is also open-source, with its code available on AdGuard Home GitHub. While our awesome Pi-Hole vs AdGuard Home post highlights most of the key differences, there are 2 main reasons why I switched.

The first reason is, AdGuard Home offers DoH capabilities for improved privacy, out of the box. Accomplishing this on Pi-Hole requires additional work. This feature alone enables the use of AdGuard Home on on-the-go mobile devices without the need to VPN in. The second reason, although minor, is the ability to add whitelists just like blocklists.

AdGuard Home is one of the apps that made it into our list of best Docker containers.

We have covered AdGuard Home in detail, explained AdGuard Home Ubuntu installation, and even shared 5 AdGuard Home configuration tips.

In this post, I will share my working AdGuard Home Docker Compose file and explain how to implement it in minutes.

AdGuard Home Docker Compose Setup

Most Docker tutorials out there give you the Docker run command and ask you to copy-paste it into Portainer. [Read: Portainer Docker Compose: FREE & MUST-HAVE Container Manager]

Adguard Home Dashboard
Adguard Home Dashboard

Having used Docker for over 5 years (and being a person of non-IT background), I strongly suggest you take the time to learn Docker compose and build your stack using it.

Docker Compose gives you portability between systems. I can use the docker-compose files from my GitHub repo in my Ubuntu Server on Proxmox, my Ubuntu Server VPS on Digital Ocean, or even my Synology NAS and they will work the same.

Which network-wide/DNS adblocker do you prefer?

View Results

Loading ... Loading ...

Although there are many ways to install, using Docker Compose for AdGuard Home is, in my opinion, the easiest way.

1. Preparing to Setup AdGuard Home Using Docker

If you already have docker and docker-compose installed and the docker environment setup (.env file), then skip to Docker Compose for AdGuard Home section below.

Requirements

First, let us start with some requirements. I won't go into a lot of details as these have been covered in detail in my Docker Media Server guide. Here is a summary of the requirements before Proceeding.

Setting Up The Docker Environment

This is also explained in detail in my Docker Guide. We are going to customize a few things with Docker before building the AdGuard Home Docker Compose file.

First, is the folder structure. I like to house all of the docker-related files and folders in one location. I call it the Docker Root Folder. Our docker-compose.yml file, .env file, etc. will be located in this folder, as shown below.

Docker Media Server Folder Structure
Docker Media Server Folder Structure

In addition, all of AdGuard Home's data will go into the appdata/adguardhome folder. For this guide, you do not need to worry about the remaining folders in the above screenshot.

Create the .env file

First, the dot in front of env is not a typo.

It is a hidden file that will store some of the key information we may use (environmental variables) repeatedly. In the docker root folder (explained above), create the .env file and add the following contents to it.

DOCKERDIR="/home/anand/docker"

Customizing the above variables is explained in detail in my Docker guide, along with the right permissions to set (very important!).

In short, DOCKERDIR is the docker root folder mentioned above.

Replace anand with your username.

2. Create the Base AdGuard Home Docker Compose File

Before we go ahead and add the Docker Compose for AdGuard Home, we will have to add a few basic elements to the compose file. Once again, this is all explained in detail in my Docker tutorial. But here is a summary of it.

Note that spacing and indentation are crucial in YAML files. Therefore, pay attention to the formatting when you copy-paste and customize the AdGuard Home Docker Compose snippet.

In your Docker Compose file, if you do not already have it, add the following:

version: "3.9"

########################### NETWORKS
networks:
  default:
    driver: bridge

########################### SERVICES
services:

We are specifying the version of Docker Compose reference to use and the default Docker bridge network. If you do not know what these are, do not worry.

We are going to make AdGuard Home accessible using the Docker Host machine's IP, using AdGuard Home's default port (e.g. http://192.68.1.211:3000). For this purpose, the above network block is sufficient.

Using Docker macvlan (RECOMMENDED)

For services like AdGuard Home and Pi-Hole, I strongly suggest a macvlan instead of using the default network described above or host networking described later.

With the default network or using the host network, you are relying on all the required ports being free on the Docker host. This is not always the case and you might encounter the "AdGuard Docker port 53 already in use" error (more on this later).

With a macvlan, AdGuard Home Docker service would act as a separate machine thereby eliminating any port conflicts.

In addition, this would give AdGuard Home its own IP address in your network.

Add the code block below right at the end of the above network block.

  dockervlan:
    name: dockervlan
    driver: macvlan
    driver_opts:
      parent: eth1 # using ifconfig
    ipam:
      config:
        - subnet: "192.168.1.0/24"
          ip_range: "192.168.1.225/32"
          gateway: "192.168.1.1"

Since my home network is in the subnet 192.168.1.X, I wanted AdGuard Home to have an IP in this range. A few things to customize. First, eth1 is the name of the network interface to use. You can find this using the ifconfig or ip address command.

If you customize the macvlan range, ensure that you update the IP address (192.168.1.225) used as example in this AdGuard Home Docker guide.

Next, customize the subnet and IP. I am assigning 192.168.1.225 to AdGuard Home. The /32 at the end means only one IP. If you plan to put multiple containers on the same macvlan, you can use other numbers per your requirement (e.g. 29 for 5 machines, 30 for 2, etc.)

3. Docker Compose for AdGuard Home

Here is the Docker-Compose for AdGuard Home that I use. Add it right under services (pay attention to indentation):

  # AdGuard Home - DNS AdBlocking
  adguardhome:
    container_name: adguardhome
    image: adguard/adguardhome
    restart: unless-stopped
    networks:
      dockervlan:
        ipv4_address: 192.168.1.225 # IP address inside the defined range
    ports:
      - 53:53/udp
      - 67:67/udp 
      - 68:68/tcp 
      - 68:68/udp 
      - 80:80/tcp 
      - 443:443/tcp 
      - 853:853/tcp 
      - 3000:3000/tcp 
    volumes:
      - $DOCKERDIR/appdata/adguardhome/conf:/opt/adguardhome/conf
      - $DOCKERDIR/appdata/adguardhome/work:/opt/adguardhome/work
      - $DOCKERDIR/shared/certs/example.com:/certs # optional: if you have your own SSL certs
You may find that the Docker Compose examples in my GitHub repo differ from the above. What is shown above is an example that is good for beginners to get started with. What is in my GitHub repo is my current setup with many features and security enhancements.

Customizing AdGuard Home Docker Setup

Here are some notes to understand and customize the above AdGuard Home docker-compose example:

  • We are using latest adguard/adguardhome docker image.
  • AdGuard Home will belong to the "dockervlan" network, to leverage the benefits listed previously.
  • In the ports section, we are exposing several AdGuard Home ports to the host. Initial setup is done via port 3000. Therefore, AdGuard Home will be available at 192.168.1.225:3000. After initial setup, AdGuard Home web interface will be available on port 80. We can make it available securely and over the internet using a reverse proxy (see below).
  • Under volumes, we are mapping a persistent volumes (conf and work) for AdGuard Home configuration. Optionally, if you have your own SSL certificates you can store them in a known location and map that folder as well. I use Traefik certificate extractor and use the certificate files to enable DoH on AdGuard Home.

Customizing Network

In the above AdGuard Home Docker Compose file, we set the network as dockervlan. That is the recommended way.

Alternatively, you can specify the AdGuard Home Docker container to use the host network. In this case, AdGuard Home functions as if it were running natively on your host system. This requires all necessary ports to be free (e.g. 80, 443, 3000, 53, etc.). To enable host networking, use the following block instead of networks:

    network_mode: 'host'

In addition, you will also need to remove the ports section. AdGuard Home should be available at http://192.168.1.211:3000 (192.168.1.211 is my Docker host), which is the same URL as the default AdGuard Home docker compose setup shown previously.

Start AdGuard Home

After customizing the AdGuard Home Docker Compose file, you can start the AdGuard Home container using the following command:

sudo docker compose -f ~/docker/docker-compose.yml up -d

Be sure to refer to my Docker guide to understand how you can follow the logs to check the start-up of the AdGuard Home docker container. You may use Dozzle logs viewer for real-time logs viewing.

If all goes well, in a few minutes you should be to access AdGuard Home using one of the URLs listed previously.

Welcome To Adguard Home
The Adguard Home Welcome Installer

Adguard Docker port 53 already in use

Commonly, the host operating system (e.g. Ubuntu/Debian) uses port 53. systemd-resolved is the user.

You can check if this is the case by executing:

sudo lsof -i -P -n | grep LISTEN

You should see an output with port 53 listed. To get around this, edit /etc/systemd/resolved.conf, uncomment DNSStubListener and set it to no, as shown below.

Systemd Resolved - Freeing Up Port 53
Systemd Resolved - Freeing Up Port 53

After making the above change, restart systemd-resolved using the command below:

sudo service systemd-resolved restart

4. AdGuard Home Setup

As mentioned before port 3000 is used only for their initial setup. So access AdGuard Home using 192.168.1.225:3000 and go through the initial setup.

We have described the 5 simple steps involved and how to complete them, in our AdGuard Home Ubuntu guide.

Once completed, the AdGuard Home web interface should be available at http://192.168.1.225:80.

5. Setup DNS Servers on Router/Devices

In short, you will have to provide your AdGuard Home IP address (e.g. 192.168.1.225) in place of the default DNS server IPs in your router or other devices. If you have never changed DNS settings, usually there should be no IP address configured in your settings.

Note: Most device settings give you the option to list at least two DNS servers. Unless you have two ad blocker instances running at home, you will provide one DNS IP address and leave the other (rest) blank as shown below. If you specify a second DNS IP that is not an ad blocker, then ads won't be blocked on some devices. Having two ad blocker instances is recommended if you are worried about one device temporarily failing and cutting off your internet.
Manual Dns Server Specification On Swisscom Routers
Manual Dns Server Specification On Swisscom Routers

6. Accessing AdGuard Home Over The Internet

Accessing AdGuard Home web UI and ad blocking from within your home network should work fine (described above). But what if you want access to AdGuard Home on-the-go from outside your home network?

There are 2 things here: 1) being able to access AdGuard Home web UI while not at home and 2) being able to block ads while not at home (over the internet).

Let's deal with the easy part first.

Accessing AdGuard Home Web Interface

If you only want to be able to access the web interface, the easiest and NOT RECOMMENDED way to do this is to forward port 80 on your router/gateway to point to your AdGuard Home servers IP address. In addition, if you have other servers that require port 80 forwarding (e.g. Traefik or Nginx Proxy Manager), then doing this is not possible anyways.

A secure and recommended way to access the AdGuard Home web interface (not ad blocking) is to put it behind a reverse proxy. But this requires a domain name or a DDNS.

Nginx Proxy Manager is very simple to setup but not very flexible.

I use and recommend Traefik. You can read all about setting it up in my Docker Traefik guide or refer to my GitHub repo.

With a reverse proxy, you can access the AdGuard Home statistics and configuration interface using a nicer URL (e.g. https://adguardhome.example.com).

Accessing AdGuard Home Ad Blocking

There are multiple ways to do this. It is better to cover those in separate guides.

  • VPN on Router: If your router allows a VPN connection, you can connect to it remotely and immediately have access to AdGuard Home. Since your internet traffic will go through your home router, which is already configured with AdGuard Home DNS server at this point, ad blocking should already be enabled.
  • VPN Mesh Network: There are third-party services such as Tailscale and ZeroTier-One that offer free mesh network plans. I use ZeroTier to tie all my key machines together in a virtual network. My Docker host is part of this network. Therefore, while on the go, I can use my Docker host's ZeroTier network IP address for my DNS server on mobile. If you take this approach then you cannot use macvlan networking.
  • DNS-over-HTTPS: This is probably the most flexible way to achieve ad blocking on the go. Unlike Pi-Hole, AdGuard Home supports DoH out of the box. But setting up DoH does require some work and I will cover this in a separate post.

Another alternative is to set up your own Wireguard network. But this is a more advanced topic.

Other Posts in the Wireguard Series:

Conclusions: Super Charging AdGuard Home on Docker

AdGuard Home is a powerful ad blocker. For an advanced user, AdGuard Home offers many advantages over Pi-Hole. Installing AdGuard Home natively on operating systems is not difficult as we explained in our Ubuntu AdGuard Home guide.

But Docker makes it much easier to install AdGuard Home, and Docker Compose simplifies it even more. With the included AdGuard Home Docker Compose and easy steps to install AdGuard Home, you should be up and running in just about 5 minutes.

After installing AdGuard Home in Docker, be sure to check out our top 5 configuration tips.

Did this post help you?
SmartHomeBeginner brings in-depth tutorials easy enough to understand even for beginners. This takes a considerable amount of work. If this post helps you, please consider supporting us as a token of appreciation:
  • Feeling generous? Become a Sponsor (discounted options) or a Patron. You will receive privileges on our Discord Server.
  • Just want to thank us? Buy us a Coffee or a Ko-Fi.
  • May be another day? Shop on Amazon using our links. Your prices won't change but we get a small commission.
  • Don't feel like spending? You can still show your support by sharing this post, linking to it in forums, or even commenting below.

Anand

Anand is a self-learned computer enthusiast, hopeless tinkerer (if it ain't broke, fix it), a part-time blogger, and a Scientist during the day. He has been blogging since 2010 on Linux, Ubuntu, Home/Media/File Servers, Smart Home Automation, and related HOW-TOs.