How to Deploy AdGuard – Network Traffic Filtering

AdGuard Home is a network-wide software for blocking ads and tracking. It acts as a DNS server that filters traffic before it reaches your devices. AdGuard Home is a single, self-contained application that many users find easier to configure. It includes built-in support for encrypted DNS (DoH/DoT) and parental controls.

This article shows you how to deploy AdGuard Home on Ubuntu 24.04 using Docker Compose. It uses Traefik to provide a secure HTTPS connection for the dashboard.

Prerequisites

Before you begin:

• Have access to an Ubuntu 24.04 server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Configure a domain name, such as adguard.example.com, to point to your server’s public IP address.

Freeing Port 53

DNS servers communicate using port 53. By default, Ubuntu 24.04 runs its own internal DNS service called systemd-resolved on this port. You must disable this internal service so that AdGuard Home can take control of port 53.

1. Stop the systemd-resolved service.

   CONSOLE

   Copy

   $ sudo systemctl stop systemd-resolved

   Explain Code

   Powered by Vultr AgentBeta

2. Disable the service so it does not start again when you reboot.

   CONSOLE

   Copy

   $ sudo systemctl disable systemd-resolved

   Explain Code

   Powered by Vultr AgentBeta

3. Remove the existing DNS configuration file.

   CONSOLE

   Copy

   $ sudo rm /etc/resolv.conf

   Explain Code

   Powered by Vultr AgentBeta

4. To ensure the server itself can still connect to the internet to download updates, you need to configure the server to use a public DNS provider. Create a new DNS configuration file.

   CONSOLE

   Copy

   $ echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf

   Explain Code

   Powered by Vultr AgentBeta

   This configuration tells your server to send its own DNS queries to 1.1.1.1, a public DNS server provided by Cloudflare.

Set Up the Directory Structure and Environment Variables

AdGuard Home requires persistent folders for configuration and data, along with environment variables that specify your domain and other settings. This section prepares both the directory structure and the .env file.

1. Create the required directories for AdGuard Home.

   CONSOLE

   Copy

   $ mkdir -p ~/adguard/{work,conf,letsencrypt}

   Explain Code

   Powered by Vultr AgentBeta
   • work – Stores the database and DNS query logs.
   • conf – Stores configuration files, settings, users, and passwords.
   • letsencrypt – Stores TLS certificates generated by Traefik.

2. Go to the project directory.

   CONSOLE

   Copy

   $ cd ~/adguard

   Explain Code

   Powered by Vultr AgentBeta

3. Create a file named .env.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following text. Replace adguard.example.com with your actual domain, admin@example.com with your email address, and UTC with your Timezone.

   INI

   Copy

   DOMAIN=adguard.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   TZ=UTC

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

Deploy with Docker Compose

A Docker Compose file is a blueprint that tells Docker how to run your services. This section covers creating a Docker Compose manifest to orchestrate the deployment. The configuration file defines the AdGuard Home and Traefik services, maps the necessary ports for DNS and web traffic, and establishes a shared network for internal communication.

1. Add your user to the docker group.

   CONSOLE

   Copy

   $ sudo usermod -aG docker $USER

   Explain Code

   Powered by Vultr AgentBeta

2. Update your group membership.

   CONSOLE

   Copy

   $ newgrp docker

   Explain Code

   Powered by Vultr AgentBeta

3. Create the docker-compose.yml file.

   CONSOLE

   Copy

   $ nano docker-compose.yml

   Explain Code

   Powered by Vultr AgentBeta

4. Paste the following content into the file:

   YAML

   Copy

   services:
     traefik:
       image: traefik:latest
       container_name: traefik
       restart: unless-stopped
       environment:
         DOCKER_API_VERSION: "1.44"
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.le.acme.httpchallenge=true"
         - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - ./letsencrypt:/letsencrypt
   
     adguard:
       image: adguard/adguardhome:latest
       container_name: adguard
       restart: unless-stopped
       environment:
         TZ: ${TZ}
       volumes:
         - ./work:/opt/adguardhome/work
         - ./conf:/opt/adguardhome/conf
       ports:
         - "53:53/tcp"
         - "53:53/udp"
         - "3000:3000/tcp"
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.adguard.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.adguard.entrypoints=websecure"
         - "traefik.http.routers.adguard.tls=true"
         - "traefik.http.routers.adguard.tls.certresolver=le"
         - "traefik.http.services.adguard.loadbalancer.server.port=80"

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   This Docker Compose configuration deploys AdGuard Home behind Traefik, enabling secure HTTPS access to the web dashboard while exposing DNS ports for network-wide ad blocking and filtering. Each service has a dedicated function in the deployment:

   adguard service (AdGuard Home)

   • Runs the official adguard/adguardhome container, providing DNS-level ad blocking, content filtering, and parental control features.
   • Exposes ports 53/tcp and 53/udp so your devices can use AdGuard Home as their DNS resolver.
   • Temporarily exposes port 3000, which is required only for the initial setup wizard. After completing setup, you can remove this port.
   • Stores persistent data in the ./work and ./conf directories, preserving your configuration across container restarts.
   • Includes Traefik labels that route HTTPS traffic for your domain (${DOMAIN}) to the AdGuard Home dashboard.
   • Internally serves its web interface on port 80, which Traefik accesses for secure frontend delivery.

   traefik service

   • Handles all external web traffic on ports 80 and 443.
   • Automatically provisions and renews TLS certificates using Let’s Encrypt via the ACME HTTP-01 challenge.
   • Redirects all HTTP requests to HTTPS for secure access.
   • Identifies and routes incoming requests to AdGuard Home using Docker labels.
   • Stores certificate data persistently in the ./letsencrypt directory.

5. Start the services.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

6. Check if the containers are running.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   Note

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Initial Configuration

AdGuard Home has an initial setup wizard that you must complete before the dashboard becomes active.

1. Open your web browser and go to your server's IP address on port 3000, such as http://SERVER_IP:3000.

2. Click "Get Started".

3. You will see two settings: "Admin Web Interface" and "DNS Server". Make sure they are set to the following values:

   • Admin Web Interface:
     • Listen interface: Leave as All interfaces.
     • Port: Change this to 80. This is the internal container port that Traefik will route to.
   • DNS Server:
     • Listen interface: Leave as All interfaces.
     • Port: Leave as 53.

   Click Next.

4. Enter your desired Username and a strong Password. Click Next.

5. You'll land on the Configure your devices page, where you'll see the configuration settings for various types of devices. Click Next.

6. The setup finishes. Click Open Dashboard. The page will not load because you're trying to access it via http://SERVER_IP:3000, but AdGuard has now moved to port 80 inside the container, accessible only via your domain through Traefik.

7. To access the dashboard, open a new tab and navigate to https://adguard.example.com. You should now see the HTTPS-secured login screen.

   

Security Configuration

By default, AdGuard Home might accept DNS queries from anyone. You must restrict this.

1. Log in to your dashboard.
2. Go to Settings > DNS Settings.
3. Scroll down to Access Settings.
4. In the Allowed clients section, enter the IP addresses of the devices you wish to use with AdGuard Home.
5. Click Save.

Client Configuration & Testing

Now you can test if the server is working.

1. Run this command from your local computer to query the DNS records of a known ad domain flurry.com. Replace SERVER_IP with your server's public IP address.

   CONSOLE

   Copy

   $ dig @SERVER_IP flurry.com

   Explain Code

   Powered by Vultr AgentBeta

   If the answer section returns 0.0.0.0, AdGuard Home is successfully blocking ad domains on your network.

2. Run this command to verify that normal websites are still resolving correctly.

   CONSOLE

   Copy

   $ dig @SERVER_IP vultr.com

   Explain Code

   Powered by Vultr AgentBeta

   You should see the domain A records of vultr.com in the output.

Conclusion

You have successfully deployed AdGuard Home on Ubuntu 24.04 using Docker Compose and secured the web dashboard with HTTPS through Traefik. Your server is now capable of blocking ads, trackers, and unwanted content at the DNS level for every device that uses it. For more information, refer to AdGuard Knowledge Base.