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

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, AdGuard Home on Raspberry Pi, 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]

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.

 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

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.

• Install Docker on Ubuntu
• Install Docker Compose on Ubuntu
• You do not need a domain name for this tutorial, but if you are going to expose AdGuard Home to the internet it may help (but still not required)

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.

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.

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.

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

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.

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.

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.

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, which is discussed in our WireGuard Docker post.

Other Posts in the Wireguard Series:

• Wireguard VPN Intro in 15 min: Amazing new VPN Protocol
• Complete Wireguard Setup in 20 min – Better Linux VPN Server
• Wireguard Windows Setup: Powerful VPN for Windows
• Wireguard Mac OS Client Setup – The sleek new VPN
• Wireguard Android Client Setup – Simple and Secure VPN
• Ultimate WireGuard Docker Compose: with CF and Traefik Support

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.