---
title: Adguard Home
description: Install AdGuard Home for network-wide ad and tracker blocking with DNS-over-HTTPS, client management, and custom filtering rules.
---


:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}
# Adguard Home

::note
🎯 __Goals:__

- Install and deploy Adguard
- Expose Adguard
- Secure DNS queries with SSL/TLS
- Configure client devices
::

[AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) is a DNS server that blocks ads and tracking at the system level. Once configured, it will protect ALL your home devices without the need for any client-side software.

It works as a DNS server that redirects tracking domains to a “black hole,” preventing your devices from connecting to them.

In practice, once it's in place, all you need to do is set your devices to use Adguard as their DNS server.

**Quick reminder of how DNS works:**

When you visit a site or use an app, it makes requests to various domains to load content, ads in particular. Your device doesn’t know the IP addresses of these domains, so it contacts a _Domain Name Server_ (DNS), which returns the current IP address.

By default, your device uses your ISP's DNS server, which is usually configured in your router or, for mobile devices, at the carrier’s CGNAT level. You can change this in your browser settings, your device’s system settings, or even directly in your router, depending on your ISP.

Adguard will act as a middleman between your device and the upstream DNS servers. If you configure your devices to use Adguard:

- If the domain is not in a blocklist, Adguard queries the upstream DNS servers and returns the correct IP to your device.
- If the domain *is* in a blocklist, Adguard will block the request and return nothing, so the associated content won’t load.

This is how ads and malicious domains are blocked: Adguard blocks only the bad domains, allowing the rest of the page to load normally.

![Picture](/img/serveex/adguard.svg)

## Installation

::file-tree
---
tree:
  /:
    - docker:
      - adguard:
        - confdir/
        - workdir/
        - compose.yaml
        - .env
---
::

::note

We will also mount the `/docker/swag/config/etc/letsencrypt` folder to access Swag's SSL certificate.
::

Open Dockge and click `compose`

Name the stack `adguardhome` and paste the configuration below:

```yaml [compose.yaml]
---
services:
  adguardhome:
    container_name: adguard
    image: adguard/adguardhome
    restart: unless-stopped
    ports:

      - 53:53/udp
      - 8080:80/tcp
      - 4443:443/tcp
      - 853:853/tcp
      - 3000:3000/tcp
    volumes:

      - /docker/adguardhome/confdir:/opt/adguardhome/conf
      - /docker/adguardhome/workdir:/opt/adguardhome/work
      - /docker/swag/config/etc/letsencrypt:/swag-ssl:ro
```

::tip{icon=""}
✨ __Tip:__ Add the watchtower label to each container to automate updates

```yaml [compose.yaml]
services:
  adguardhome:
    # ...
    labels:

      - com.centurylinklabs.watchtower.enable=true
```
::

Deploy the stack.

Go to `http://yourserverip:3000` and follow the setup instructions.

That’s it! Adguard is deployed.

## Exposing AdGuard with SWAG
To make AdGuard usable from outside your home network, you need to expose it.

::note

__Prerequisites:__ We assume you've created a subdomain like `adguard.mydomain.com` in your [DNS zone](/general/networking/dns) with a `CNAME` pointing to `mydomain.com`, and that you’ve already forwarded port `443` from your router to port `443` on your server in your [NAT rules](/general/networking/nat). Also forward port `53` and port `853` to your server. These ports are used to route DNS requests.
::

::warning

Do not use Cloudflare tunnels to expose AdGuard, and make sure any proxying is disabled.
::

In Dockge, go to the SWAG stack and edit the compose file to add the AdGuard network:

```yaml [compose.yaml]
services:
  swag:
     container_name: # ...
      # ... 
     networks:             # Connect the container to the custom network 
      # ...           

      - adguard            # Name of the network declared in the stack
    
networks:                  # Define the custom network
  # ...
  adguard:                 # Name of the network declared in the stack
    name: adguard_default  # Actual name of the external network
    external: true         # Specifies that this is an external network
```

::note

We assume here that the AdGuard network is named `adguard_default`. You can verify the connection is working by visiting the SWAG dashboard at http://yourserverip:81.
::

Restart the stack by clicking "Deploy" and wait for SWAG to be fully operational.

Create and open the file `adguard.subdomain.conf`

::tip{icon=""}
✨ __Tip for terminal haters:__
You can use [File Browser Quantum](/serveex/files/file-browser-quantum) to browse and edit files instead of using terminal commands.
::

```bash [Terminal]
sudo nano /docker/swag/config/nginx/proxy-confs/adguard.subdomain.conf
```

Paste the configuration below:

```nginx [adguard.subdomain.conf]
## Version 2023/05/31
# make sure that your adguard container is named adguard
# make sure that your dns has a cname set for adguard

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name adguard.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    #if ($lan-ip = yes) { set $geo-whitelist yes; }
    #if ($geo-whitelist = no) { return 404; }
    if ($geo-blacklist = no) { return 404; }

    # enable for ldap auth (requires ldap-location.conf in the location block)
    #include /config/nginx/ldap-server.conf;

    # enable for Authelia (requires authelia-location.conf in the location block)
    #include /config/nginx/authelia-server.conf;

    # enable for Authentik (requires authentik-location.conf in the location block)
    #include /config/nginx/authentik-server.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable for ldap auth (requires ldap-server.conf in the server block)
        #include /config/nginx/ldap-location.conf;

        # enable for Authelia (requires authelia-server.conf in the server block)
        #include /config/nginx/authelia-location.conf;

        # enable for Authentik (requires authentik-server.conf in the server block)
        #include /config/nginx/authentik-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /control {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /dns-query {
        # to properly use this please set `allow_unencrypted_doh: true` and `force_https: false` in adguard
        # see https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }
}
```

## Protecting AdGuard with TinyAuth
Add [TinyAuth](/serveex/security/tinyauth)'s forward-auth check directly to `adguard.subdomain.conf`, the same way as [the TinyAuth guide](/serveex/security/tinyauth#protecting-an-app-via-reverse-proxy). The `/dns-query` location is left out of the `auth_request` check, since DNS-over-HTTPS clients can't do an interactive login:

```nginx [adguard.subdomain.conf]{28-40,43-44,69-70}
## Version 2023/05/31
# make sure that your adguard container is named adguard
# make sure that your dns has a cname set for adguard

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name adguard.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    #if ($lan-ip = yes) { set $geo-whitelist yes; }
    #if ($geo-whitelist = no) { return 404; }
    if ($geo-blacklist = no) { return 404; }

    # enable for ldap auth (requires ldap-location.conf in the location block)
    #include /config/nginx/ldap-server.conf;

    # enable for Authelia (requires authelia-location.conf in the location block)
    #include /config/nginx/authelia-server.conf;

    # enable for Authentik (requires authentik-location.conf in the location block)
    #include /config/nginx/authentik-server.conf;

    location /tinyauth {
        internal;
        proxy_pass http://tinyauth:3000/api/auth/nginx;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Uri $request_uri;
    }

    location @tinyauth_login {
        return 302 https://tinyauth.mydomain.com/login?redirect_uri=$scheme://$http_host$request_uri;
    }

    location / {
        auth_request /tinyauth;
        error_page 401 = @tinyauth_login;

        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable for ldap auth (requires ldap-server.conf in the server block)
        #include /config/nginx/ldap-location.conf;

        # enable for Authelia (requires authelia-server.conf in the server block)
        #include /config/nginx/authelia-location.conf;

        # enable for Authentik (requires authentik-server.conf in the server block)
        #include /config/nginx/authentik-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /control {
        auth_request /tinyauth;
        error_page 401 = @tinyauth_login;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location /dns-query {
        # to properly use this please set `allow_unencrypted_doh: true` and `force_https: false` in adguard
        # see https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration#configuration-file
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app adguard;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }
}
```

::note

The `location /tinyauth` block runs inside SWAG's own container, so SWAG needs to be on TinyAuth's Docker network to reach it by name (`tinyauth` here). This should already be set up from [exposing TinyAuth itself](/serveex/security/tinyauth#exposing-tinyauth-with-swag). If you run into an error, double-check SWAG's compose file still has that network attached.
::

::tip{icon=""}
✨ __Tip:__ 
<br/><br/>
You can protect this app with Authentik instead of TinyAuth by opening `adguard.subdomain.conf` and removing the `#` in front of `include /config/nginx/authentik-server.conf;`{lang=nginx} and `include /config/nginx/authentik-location.conf;`{lang=nginx}. Don’t forget to [create an application and a provider in Authentik](/serveex/advanced/authentik/#protecting-an-app-via-reverse-proxy). You’ll need to exclude the URL `https://adguard.mydomain.com/dns-query` from authentication:

- Edit the AdGuard provider
- Under *Advanced Protocol Settings > Authenticated Paths*, enter `^/dns-query`
::

Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.

And that's it! AdGuard is now exposed!

## Configure SSL/TLS Encryption
Encryption is essential if you want to keep your queries to AdGuard private. Encrypting your queries ensures that no one, not even your ISP, can see your history. It also ensures that only your server can respond to you.

To configure encryption:

- Go to _Settings_ then _Encryption_.
- Set the options as follows:

![Picture](/img/serveex/adguard-chiffrement.png)

- Below, in the _Certificates_ section, check _Use file path for certificate_
- In the input field, enter `/swag-ssl/live/mydomain.com/fullchain.pem`, replacing `mydomain.com` with your actual domain.
- For _Private Key_, check _Use file path for private key_
- In the input field, enter `/swag-ssl/live/mydomain.com/privkey.pem`, replacing `mydomain.com` accordingly.
- Save

Done! Your future DNS queries are now protected!

## Configure Devices
You have several options (which you can combine) to configure your devices.
### Secure the Local Network
You can secure your local network with AdGuard by configuring your router to direct all DNS queries by default to AdGuard instead of your ISP’s DNS. Note: your router must allow DNS changes (Orange routers do not).

This option is usually in the _DHCP_ settings. Make sure to add a fallback DNS server such as:

- Cloudflare: `1.1.1.1`
- Google: `8.8.8.8`

Without this, if your server goes down, your devices will lose internet access.

::note

Some devices may have a separate DNS configured and may not use the router’s DNS.
::

### Force a Browser to Use AdGuard

In your browser, you can configure a DNS to force it to use AdGuard Home.
In the settings, specify the address `https://adguard.mydomain.com/dns-query`

### Configure AdGuard at the System Level on Windows

In Windows, you need to configure AdGuard for each network adapter you want to use.

- Go to _Home > Network & Internet_, then select the network adapter to modify
- Click _Edit DNS_ (sometimes under _Hardware Properties_)
- Choose `Manual`
- Enable IPv4
- Enter your server’s public IP (the one accessible from the internet)
- Enable _DNS over HTTPS (manual template)_
- Disable _Fallback to plaintext_
- Save

All programs using that network adapter will now be filtered by AdGuard.

## Add Filters

- Go to the settings and change the filters.