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:
- Configure the network interface.
- Configure the DNS server.
- Create your administrator account.
- 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.