Adguard Home is a network-wide software for blocking ads and tracking. This is your very own DNS Server. Similar to Adguard DNS, Google Public DNS, Cloudflare DNS, Quad9, OpenDNS and bunch of other. It re-routes tracking domains to a “black hole”, thus preventing your devices from connecting to those servers, thus saving bandwidth and improving your privacy. After you set it up, it’ll cover ALL your home devices, and you don’t need any client-side software for that.
We need a VPS server in which we’ll install this software, in addition Docker is required. The domain is also required for the DNS-over-HTTPS and DNS-over-TLS and DNSCrypt technologies. Setting up VPS server is out of scope of this tutorial, we’ll only give you instructions on how to install and use this software.
The following parameters are assumed:
First we need to create the directory for our Adguard Home Docker persistent configuration confdir and data directory, the workdir directory may become large depengin on your logging settings. For this example, we will put it on the user’s home directory be sure to have adequate disk space!
Open up your preferred Terminal emulator:
$ mkdir -p ~/docker
$ mkdir -p ~/docker/adguardhome
$ mkdir -p ~/docker/adguardhome/confdir
$ mkdir -p ~/docker/adguardhome/workdir
The commands above will create the docker config and data directory for the Adguard Home.
Getting the latest stable docker image:
$ docker pull adguard/adguardhome
Creating the docker container and running Adguard Home”
docker run --name adguardhome\
--restart unless-stopped\
-v /home/user/docker/adguardhome/workdir:/opt/adguardhome/work\
-v /home/user/docker/adguardhome/confdir:/opt/adguardhome/conf\
-p 53:53/tcp -p 53:53/udp\
-p 67:67/udp -p 68:68/udp\
-p 80:80/tcp -p 443:443/tcp -p 443:443/udp -p 3000:3000/tcp\
-p 853:853/tcp\
-p 784:784/udp -p 853:853/udp -p 8853:8853/udp\
-p 5443:5443/tcp -p 5443:5443/udp\
-d adguard/adguardhome
Port mappings (if no IP address is specified on each port it would be listening to 0.0.0.0 or all IPv4,:: or all IPv6 addresses.):
-p 53:53/tcp -p 53:53/udp: plain DNS.
-p 67:67/udp -p 68:68/tcp -p 68:68/udp: add if you intend to use AdGuard Home as a DHCP server. Don’t enable this over the internet!
-p 80:80/tcp -p 443:443/tcp -p 443:443/udp -p 3000:3000/tcp: add if you are going to use AdGuard Home’s admin panel as well as run AdGuard Home as an HTTPS/DNS-over-HTTPS server. Note: If you have an existing web server that is listening to 443/tcp this would fail. You may need to change the port for DNS-over-HTTPS for this to work with your web server.
Port 3000 is the dashboard UI, and 443 is for the DNS-over-HTTPS port.
-p 853:853/tcp: add if you are going to run AdGuard Home as a DNS-over-TLS server.
-p 784:784/udp -p 853:853/udp -p 8853:8853/udp: add if you are going to run AdGuard Home as a DNS-over-QUIC server. You may only leave one or two of these.
-p 5443:5443/tcp -p 5443:5443/udp: add if you are going to run AdGuard Home as a DNSCrypt server.
For our sample config:
Parameters:
No web server (No binding to Port 80 and 443). Port 3000 is exposed to the internet. No DHCP server configured.
$ docker run --name adguardhome\
--restart unless-stopped\
-v /home/user/docker/adguardhome/workdir:/opt/adguardhome/work\
-v /home/user/docker/adguardhome/confdir:/opt/adguardhome/conf\
-p 53:53/tcp -p 53:53/udp\
-p 80:80/tcp -p 443:443/tcp -p 443:443/udp -p 3000:3000/tcp\
-p 853:853/tcp\
-p 784:784/udp -p 853:853/udp -p 8853:8853/udp\
-p 5443:5443/tcp -p 5443:5443/udp\
-d adguard/adguardhome
You can now visit the Adguard Home Dashboard on your http://domain.com:3000.
Now, if you have an existing program listening to port 80 and 443 like a web server. We need to use an alternative port for the DNS-over-HTTPS. We should also put the dashboard behind reverse proxy like on the nginx web server, for this to be done, we need stop the adguard container, reconfigure and rebuild it. The existing configuration won’t be erased.
Stopping and Removing the old container:
$ docker stop adguardhome
$ docker rm adguardhome
If you have problem executing the commands above, we can remove the specific image:
List your running docker containers:
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
2ccb4a6b8132 adguard/adguardhome "/opt/adguardhome/Ad…" 13 days ago Up 13 days 67-68/udp, 0.0.0.0:53->53/udp, :::53->53/udp, 0.0.0.0:53 ...
Stopping and Removing that container:
$ docker stop 2ccb4a6b8132
$ docker rm 2ccb4a6b8132
Change the docker container parameter like below:
-p 127.0.0.1:8080:80/tcp -p 127.0.0.1:3000:3000/tcp \
The new docker configuration:
docker run --name adguardhome\
--restart unless-stopped\
-v /home/user/docker/adguardhome/workdir:/opt/adguardhome/work\
-v /home/user/docker/adguardhome/confdir:/opt/adguardhome/conf\
-p 53:53/tcp -p 53:53/udp\
-p 127.0.0.1:8080:80/tcp -p 8443:8443/tcp -p 8443:8443/udp -p 127.0.0.1:3000:3000/tcp \
-p 853:853/tcp\
-p 784:784/udp -p 853:853/udp -p 8853:8853/udp\
-p 5443:5443/tcp -p 5443:5443/udp\
-d adguard/adguardhome
Parameters: 8443 is now the DNS-over-HTTPS port, Dashboard UI port 3000 is now binding to localhost, port 80 is binded to 8080.
The DNS-over-HTTPS can now be found at https://domain.com:8443/dns-query.
To access the dashboard we need to edit your existing nginx configuration:
Yours may vary.
$ sudo nano /etc/nginx/sites-available/default.conf
This configuration is derived from https://github.com/AdguardTeam/AdGuardHome/wiki/FAQ#how-to-configure-a-reverse-proxy-server-for-adguard-home.
Append the location /aghome inside your server directive.
server {
listen 443 ssl http2;
...
location /aghome/ {
proxy_pass http://127.0.0.1:3000/;
proxy_redirect / /aghome/;
proxy_cookie_path / /aghome/;
}
...
}
Verify that configuration, before reloading the webserver
$ sudo nginx -t
The output when the configuration is Ok:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
You can now visit the dashboard at https://domain.com/aghome and continue with configurating Adguard Home. Refer to the References for more information about Adguard Home.
Reference: