Self-host AdGuard Home with Docker Compose

Blocco di pubblicità e tracker a livello di rete per tutti i propri dispositivi

This is still a work in progress.

The generated compose file and instructions may not be complete or correct for every app yet. Please report any issues you encounter to contact@bitflake.com.

The steps below take a few minutes end to end.

Docker compose setup and file
save the generated compose and env files.
Start AdGuard Home with Docker Compose
bring the stack up and check it's healthy.

Requirements

You'll need these installed on the machine you're deploying to:

Docker

Packages AdGuard Home and everything it depends on into an isolated container, so it runs the same way on your machine as it does everywhere else.

Install guide

Docker Compose

Reads docker-compose.ymland starts everything in it together. Ships with Docker Desktop. On Linux servers it's usually a separate install.

Install guide

1. Docker compose setup and file

Create a folder for AdGuard Home and save the file below into it as docker-compose.yml. It describes every container the stack needs — AdGuard Homeitself and any supporting services, such as its database — along with the ports, volumes and environment variables each one uses. You'll also need an empty .env file in the same folder; Docker Compose reads it automatically and uses it to fill in the ${VARIABLE}references you'll see in the file below.

docker-compose.yml

version: "3.9"
services:
  adguard-home:
    image: adguard/adguardhome:v0.107.78
    restart: unless-stopped
    ports:
      - 3000:3000
    volumes:
      - bin:/opt/adguardhome/bin
      - conf:/opt/adguardhome/conf
      - work:/opt/adguardhome/work
    configs:
      - source: adguard-home-AdGuardHome.seed.yaml
        target: /opt/adguardhome/AdGuardHome.seed.yaml
    entrypoint:
      - /bin/sh
      - -c
      - cp -n /opt/adguardhome/AdGuardHome.seed.yaml /opt/adguardhome/conf/AdGuardHome.yaml; cp /opt/adguardhome/AdGuardHome /opt/adguardhome/bin/AdGuardHome; exec /opt/adguardhome/bin/AdGuardHome --no-check-update -c /opt/adguardhome/conf/AdGuardHome.yaml -w /opt/adguardhome/work
volumes:
  bin: null
  conf: null
  work: null
configs:
  adguard-home-AdGuardHome.seed.yaml:
    content: |
      http:
        address: 0.0.0.0:3000
        doh:
          insecure_enabled: true
      users:
        - name: admin
          password: $$2a$$10$$ZB8gFj/vevL0N3htZ5cQTesuA5ai08xXbYofcSxT5yDK4BGZpvlcG
      dns:
        bind_hosts:
          - 0.0.0.0
        port: 5353
        # The upstream is addressed by IP, not hostname, which matters here.
        # Resolving a named upstream needs a bootstrap server on port 53, and
        # only the cluster's own resolver is reachable on that port, so AdGuard
        # falls back to its built-in bootstrap addresses and times out after 20
        # seconds. That stalls far more than DNS: AdGuard resolves its own
        # outbound requests through the configured upstream too, so a broken
        # bootstrap also stops filter lists from ever downloading. Cloudflare
        # lists 1.1.1.1 in its certificate, so this URL needs no bootstrap at
        # all. Leave bootstrap_dns empty; it isn't consulted for an IP literal.
        upstream_dns:
          - https://1.1.1.1/dns-query
        bootstrap_dns: []
      filters:
        - enabled: true
          url: https://adguardteam.github.io/HostlistsRegistry/assets/filter_1.txt
          name: AdGuard DNS filter
          id: 1
      schema_version: 34

Volumes

AdGuard Home stores its data in named Docker volumes, so it survives container restarts and updates:

bin mounted at /opt/adguardhome/bin: A copy of the AdGuard Home program, refreshed from the image every time the app starts.
conf mounted at /opt/adguardhome/conf: AdGuard Home's settings: your filter subscriptions, custom rules, client definitions and the admin account.
work mounted at /opt/adguardhome/work: Query log, statistics and the downloaded copies of every filter list.

2. Start AdGuard Home with Docker Compose

From the folder with docker-compose.yml and .env, run:

Terminal

Start AdGuard Home and all its supporting services in the background.

docker compose up -d

The -d flag runs the stack in the background so it keeps running after you close the terminal. Docker will pull the images the first time, which can take a minute or two.

To check on it afterwards: docker compose ps shows whether containers are healthy, and docker compose logs -f follows their logs if something looks wrong. Once it's running, open http://localhost:3000 in your browser.