AdGuardHome-ToolBox

Own your stack. Skip the rent.

Installation Guides & Help

How to Install Docker, AdGuard Home and AdGuardHome-ToolBox on Raspberry Pi OS, Debian, or Ubuntu Server

This guide is designed show you how to install Docker, install AdGuard Home, and install AdGuardHome-Toolbox on a Raspberry Pi or small Linux server. If you already have docker installed you can skip to the end of the guide to Step 28 as this is designed for all levels of users, novice to experts.

The guide assumes you are starting from scratch and do not have Docker installed and while it tries to cover a lot there maybe areas not covered or wrong, so Google , Gemini & ChatGPT are your friends.

You do not need previous Docker experience. Follow the steps in order and copy and paste the commands exactly as shown.

This guide is intended for:

  • Raspberry Pi OS 64-bit
  • Debian 64-bit
  • Ubuntu Server 64-bit

Important: Your server should have a stable IP address. The easiest option for most home networks is to create a DHCP reservation for the server in your router.

Before You Start

You will need:

  • A Raspberry Pi or Linux server
  • A working internet connection
  • A Linux user account with Sudo access
  • Your server connected to your home network
  • A stable IP address for the server

Your server does not need a monitor or keyboard if you already know how to connect to it using SSH.

For example:

ssh [email protected]

Replace Username and 192.168.1.1 with your own username and server IP address.

Give Your Server a Stable IP Address

This is strongly recommended before setting up network-wide DNS.

For example, suppose your Raspberry Pi currently has:

192.168.1.100

You want that address to remain the same.

The easiest option for most home networks is to create a DHCP reservation in your router.

This tells your router:

Always give this Raspberry Pi the same IP address.

You will use this IP address later when configuring your network’s DNS server.

Step 1: Find Out Which Linux System You Are Running

If you are not sure which version of Linux you have, run:

cat /etc/os-release

You should see information identifying your operating system.

You can also check whether your system is 64-bit:

dpkg --print-architecture

A modern 64-bit Raspberry Pi should normally report:

arm64

A typical 64-bit Intel/AMD system will report:

amd64

For a new Raspberry Pi installation, 64-bit Raspberry Pi OS is recommended.

Step 2: Update Linux

Before installing anything, update the package list:

sudo apt update

Then install available updates:

sudo apt upgrade -y

When finished, reboot:

sudo reboot

If you are connected over SSH, your connection will disconnect.

Wait a few seconds and reconnect.

Step 3: Check Whether Docker Is Already Installed

Run:

docker --version

If you see:

docker: command not found

that’s fine. Continue to the next step.

If Docker is already installed and you see a version number, do not reinstall it. You can skip ahead to Step 8: Make Sure Docker Starts Automatically.

Step 4: Remove Conflicting Docker Packages

Linux distributions sometimes provide their own Docker-related packages.

To avoid conflicts with Docker’s official packages, run:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
    sudo apt remove -y $pkg
done

If some of these packages were not installed, you may see messages saying they could not be found.

That is normal.

Step 5: Install the Required Docker Packages

Install the packages needed to add Docker’s official repository:

sudo apt update
sudo apt install -y ca-certificates curl

Create the directory where the Docker signing key will be stored:

sudo install -m 0755 -d /etc/apt/keyrings

Download Docker’s official signing key:

sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc

Make the key readable:

sudo chmod a+r /etc/apt/keyrings/docker.asc

Step 6: Add Docker’s Official Repository

This step depends on which operating system you are using.

Raspberry Pi OS

First check your operating system:

cat /etc/os-release

If you are running Raspberry Pi OS, use:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/raspbian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Then:

sudo apt update

Do not use the Ubuntu Docker repository on Raspberry Pi OS.

Debian

If you are running Debian, use:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Then:

sudo apt update

Ubuntu Server

If you are running Ubuntu Server, use:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Then:

sudo apt update

Step 7: Install Docker

Install Docker Engine and Docker Compose:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Docker is now installed.

Step 8: Make Sure Docker Starts Automatically

Enable Docker so it starts whenever the Raspberry Pi or server boots:

sudo systemctl enable docker

Start Docker now:

sudo systemctl start docker

Check its status:

sudo systemctl status docker

Look for:

Active: active (running)

Press Q to leave the status screen.

Step 9: Allow Your User to Run Docker

By default, Docker commands may require “sudo”.

Add your current Linux user to the Docker group:

sudo usermod -aG docker $USER

You must log out and log back in before this change takes effect.

If you’re connected over SSH:

exit

Then reconnect to your server.

For example:

ssh [email protected]

Step 10: Test Docker

Run:

docker --version

Then run Docker’s test container:

docker run hello-world

If everything is working, Docker will download a small test image and display a message confirming that Docker is working.

If “docker run hello-world” works, Docker is ready.

Step 11: Check for a DNS Port Conflict

AdGuard Home needs port 53 for DNS.

Check whether something else is already using port 53:

sudo ss -lntup | grep ':53'

If nothing is returned, that’s good.

If you see something listening on port 53, a service such as “systemd-resolved” may already be using it.

Check:

sudo systemctl status systemd-resolved

Do not randomly disable DNS services.

Your Linux server needs DNS to access the internet, and changing the wrong setting can cause the server itself to lose DNS access.

Step 12: Create AdGuard Home Storage Directories

AdGuard Home needs somewhere to store its configuration and working data.

Create the directories:

sudo mkdir -p /opt/adguardhome/work
sudo mkdir -p /opt/adguardhome/conf

Give your user ownership:

sudo chown -R $USER:$USER /opt/adguardhome

Your AdGuard Home configuration will be stored in these directories.

Step 13: Download AdGuard Home

Download the AdGuard Home Docker image:

docker pull adguard/adguardhome:latest

Step 14: Start AdGuard Home

Run:

docker run -d \
  --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 3000:3000/tcp \
  adguard/adguardhome:latest

Important: The “–restart unless-stopped” option means Docker will automatically restart AdGuard Home after a reboot and if the container unexpectedly stops.

The ports are:

  • 53 TCP/UDP — DNS
  • 3000 TCP — initial setup
  • 80 TCP — AdGuard Home web interface

Step 15: Make Sure AdGuard Home Is Running

Run:

docker ps

You should see a container named:

adguardhome

You can also check the logs:

docker logs adguardhome

If the container is running, you’re ready to continue.

Step 16: Find Your Server’s IP Address

Run:

hostname -I

You may see:

192.168.1.100

Your address will probably be different.

Write this IP address down.

Step 17: Open the AdGuard Home Setup Page

From another computer or phone connected to the same network, open a web browser.

Go to:

http://YOUR-SERVER-IP:3000

For example:

http://192.168.1.100:3000

You should see the AdGuard Home setup wizard.

Follow the wizard to:

  1. Configure the network interface.
  2. Configure the DNS server.
  3. Create your administrator account.
  4. Configure upstream DNS servers.

Save your AdGuard Home username and password somewhere safe.

Step 18: Open the AdGuard Home Dashboard

After the initial setup, the dashboard should normally be available at:

http://YOUR-SERVER-IP

For example:

http://192.168.1.100

Log in using the administrator account you created.

Step 19: Configure Your Router to Use AdGuard Home

This is the step that actually makes AdGuard Home work across your network.

Installing AdGuard Home does not automatically make every device use it.

Your router normally gives devices their DNS settings through DHCP.

If your Raspberry Pi is:

192.168.1.100

configure your router’s DNS server to:

192.168.1.100

Your router may call this setting:

  • DNS Server
  • DHCP DNS
  • LAN DNS
  • Primary DNS
  • Local DNS
  • DHCP Server DNS

The exact location depends on your router.

After changing the setting, devices may need to reconnect to Wi-Fi or renew their DHCP lease.

Step 20: Test DNS

On another Linux computer, install DNS testing tools if necessary:

sudo apt install -y dnsutils

Then test AdGuard Home directly:

nslookup example.com 192.168.1.100

Replace 192.168.1.100 with your actual server IP.

You can also use:

dig @192.168.1.100 example.com

If you receive a response, AdGuard Home is responding to DNS queries.

Step 21: Check the AdGuard Home Dashboard

Go back to:

http://YOUR-SERVER-IP

Once your devices begin using AdGuard Home, you should see DNS requests appearing in the dashboard.

You can see:

  • DNS requests
  • Blocked requests
  • Client devices
  • Query logs
  • Frequently requested domains
  • Frequently blocked domains

Step 22: IPv6

If your network uses IPv6, you should configure IPv6 DNS as well.

Otherwise, some devices may use AdGuard Home for IPv4 DNS while using another DNS server over IPv6.

If you’re not using IPv6, you can skip this section.

If you are using IPv6, check your router’s IPv6 DNS settings and configure them appropriately for AdGuard Home.

Step 23: DNS-over-HTTPS

Some browsers, operating systems, and applications can bypass your router’s DNS settings by using their own encrypted DNS service.

This is commonly called DNS-over-HTTPS (DoH).

Your normal setup looks like:

Device
   ↓
Router
   ↓
AdGuard Home
   ↓
Internet

A device using its own encrypted DNS provider may instead do:

Device
   ↓
Encrypted DNS Provider
   ↓
Internet

If one device isn’t appearing in AdGuard Home, check its:

  • DNS settings
  • Browser settings
  • VPN
  • Privacy settings
  • Security software

Step 24: Verify AdGuard Home Automatically Restarts

The container was created with:

--restart unless-stopped

This means Docker will automatically start AdGuard Home after the server reboots.

Check the setting:

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' adguardhome

You should see:

unless-stopped

Step 25: Restart AdGuard Home

To manually restart AdGuard Home:

docker restart adguardhome

Then check:

docker ps

Step 26: Update AdGuard Home

Download the latest image:

docker pull adguard/adguardhome:latest

Stop the existing container:

docker stop adguardhome

Remove the container:

docker rm adguardhome

Start it again:

docker run -d \
  --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 3000:3000/tcp \
  adguard/adguardhome:latest

Your settings are preserved because they are stored in /opt/adguardhome/ on the host rather than inside the Docker container.

Step 27: Back Up AdGuard Home

Your important AdGuard Home data is stored here:

/opt/adguardhome/

Create a backup:

sudo tar -czf ~/adguardhome-backup-$(date +%Y-%m-%d).tar.gz /opt/adguardhome

Check the backup:

ls -lh ~/adguardhome-backup-*.tar.gz

For an important installation, copy the backup to another computer or storage device.

A backup stored only on the Raspberry Pi won’t help if the SD card or storage device fails.

Step 28: Install AdGuardHome-Toolbox

You can optionally install AdGuardHome-Toolbox alongside AdGuard Home.

The Toolbox will run in its own Docker container.

It will use:

  • Port 81 on the server
  • Port 8080 inside the container
  • A persistent Docker volume called adguardhome-toolbox
  • Automatic restart using unless-stopped

Download the AdGuardHome-Toolbox image:

docker pull ghcr.io/ludditious/adguardhome-toolbox:latest

If you already have an old Toolbox container, remove it:

docker rm -f adguardhome-toolbox

If you have never installed it before, Docker may say the container does not exist.

That is normal.

You can also use this version, which stays quiet if the container doesn’t exist:

docker rm -f adguardhome-toolbox 2>/dev/null || true

Step 29: Start AdGuardHome-Toolbox

Run:

docker run -d \
  --name adguardhome-toolbox \
  -p 81:8080 \
  -v adguardhome-toolbox:/data \
  --restart unless-stopped \
  ghcr.io/ludditious/adguardhome-toolbox:latest

The –restart unless-stopped option is important.

It means the Toolbox will automatically start again when your Raspberry Pi or server reboots and will restart if the container unexpectedly stops.

Step 30: Check That AdGuardHome-Toolbox Is Running

Run:

docker ps

You should see both:

adguardhome
adguardhome-toolbox

You can check the Toolbox logs:

docker logs adguardhome-toolbox

Or watch the logs live:

docker logs -f adguardhome-toolbox

Press Ctrl + C to stop watching the logs.

Step 31: Open AdGuardHome-Toolbox

Open a browser and go to:

http://YOUR-SERVER-IP:81

For example:

http://192.168.1.100:81

Port 81 is used because AdGuard Home is already using port 80.

Step 32: Verify Both Containers Automatically Restart

Check AdGuard Home:

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' adguardhome

You should see:

unless-stopped

Check AdGuardHome-Toolbox:

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' adguardhome-toolbox

You should also see:

unless-stopped

Finally, check both containers:

docker ps

You should have:

AdGuard Home
http://YOUR-SERVER-IP

AdGuardHome-Toolbox
http://YOUR-SERVER-IP:81

Both containers are configured to automatically restart after a reboot unless you manually stop them.

Useful Docker Commands

See running containers:

docker ps

See all containers, including stopped containers:

docker ps -a

View AdGuard Home logs:

docker logs adguardhome

View Toolbox logs:

docker logs adguardhome-toolbox

Restart AdGuard Home:

docker restart adguardhome

Restart AdGuardHome-Toolbox:

docker restart adguardhome-toolbox

Stop AdGuard Home:

docker stop adguardhome

Start AdGuard Home:

docker start adguardhome

Stop AdGuardHome-Toolbox:

docker stop adguardhome-toolbox

Start AdGuardHome-Toolbox:

docker start adguardhome-toolbox

Troubleshooting

Docker says “command not found”

Docker isn’t installed or your current shell cannot find it.

Run:

docker --version

If that fails, go back to Step 5: Install the Required Docker Packages.

Docker says “permission denied”

You may not have logged out and back in after adding your user to the Docker group.

Run:

groups

Look for:

docker

If it isn’t listed, log out:

exit

Then reconnect to your server.

AdGuard Home Won’t Start

Run:

docker ps -a

Then:

docker logs adguardhome

A common cause is another program already using port 53.

Check:

sudo ss -lntup | grep ':53'

Port 53 Is Already Being Used

First identify what is using it:

sudo ss -lntup | grep ':53'

Do not simply disable the service without checking what it does.

I Can’t Open Port 3000

Check that AdGuard Home is running:

docker ps

Check the logs:

docker logs adguardhome

Find your server IP:

hostname -I

Then try:

http://YOUR-SERVER-IP:3000

AdGuard Home Opens But My Devices Aren’t Being Filtered

Your devices may not actually be using AdGuard Home.

Check your router’s DHCP/DNS settings.

The DNS server should point to the IP address of your AdGuard Home server.

For example:

192.168.1.100

Also check whether the device is using:

  • DNS-over-HTTPS
  • DNS-over-TLS
  • A VPN
  • A manually configured DNS server
  • IPv6 DNS
  • Security software with its own DNS service

AdGuardHome-Toolbox Won’t Start

Check:

docker ps -a

Then:

docker logs adguardhome-toolbox

Check whether port 81 is already being used:

sudo ss -lntup | grep ':81'

If another application is using port 81, you can use another port.

For example:

docker rm -f adguardhome-toolbox

Then:

docker run -d \
  --name adguardhome-toolbox \
  -p 8081:8080 \
  -v adguardhome-toolbox:/data \
  --restart unless-stopped \
  ghcr.io/ludditious/adguardhome-toolbox:latest

You would then access the Toolbox at:

http://YOUR-SERVER-IP:8081

Final Setup

When everything is finished, your Raspberry Pi or Linux server should look roughly like this:

                    INTERNET
                       |
                       |
                  HOME ROUTER
                       |
                       |
              +--------+--------+
              |                 |
              |                 |
              v                 v
        AdGuard Home       Other Services
          Docker
        Port 53 / DNS
              |
              |
       +------+------+
       |             |
       v             v
    Laptop         Phone

Your server will have two Docker containers:

Linux / Raspberry Pi
        |
      Docker
        |
        +--- AdGuard Home
        |      |
        |      +--- DNS: Port 53
        |      +--- Web: Port 80
        |      +--- Setup: Port 3000
        |
        +--- AdGuardHome-Toolbox
               |
               +--- Web: Port 81

Both containers use –restart unless-stopped.

This means they will automatically start when Docker starts after a reboot and will restart if they unexpectedly stop.

The most important things to remember:

  • Keep the server’s IP address stable.
  • Make sure port 53 is available for AdGuard Home.
  • Configure your router to give clients the AdGuard Home IP as their DNS server.
  • Configure IPv6 DNS if your network uses IPv6.
  • Be aware that some devices and browsers can bypass normal DNS using encrypted DNS.
  • Back up /opt/adguardhome/.
  • Do not expose your DNS server directly to the public internet.
  • Both AdGuard Home and AdGuardHome-Toolbox are configured to automatically restart.