Setting Up an AdGuard Home Cluster with Shared Configuration on Docker Swarm and Raspberry Pi

In this guide, we will walk you through the steps to set up an AdGuard Home cluster, with one node running in a Docker Swarm environment and another node running on a standalone Raspberry Pi using a Docker configuration file. By leveraging Docker Swarm and a standalone Raspberry Pi, you ensure flexibility, high availability, and a consistent configuration across your cluster.

Why AdGuard Home?

AdGuard Home is a network-wide ad blocker that acts as a DNS server to block ads, trackers, and more. It's lightweight, highly customizable, and perfect for home or small-office use.

AdGuard Home | Network-wide software for any OS: Windows, macOS, Linux

AdGuard Home is a network-wide software for blocking ads & tracking. After you set it up, it’ll cover ALL your home devices, and you don’t need any client-side software for that.

Network-wide software for any OS: Windows, macOS, Linux

Prerequisites

1. Docker Swarm cluster: Ensure you have a Docker Swarm cluster running with at least one manager and worker node.
2. Raspberry Pi: A standalone Raspberry Pi with Docker installed.
3. NFS server: An NFS server to host the shared configuration files.
4. Proper networking: Ensure your Docker Swarm nodes and Raspberry Pi have network access to the NFS server.

Configuration Overview

The setup involves deploying AdGuard Home as follows:

• Node 1: Running in Docker Swarm with shared configuration stored on an NFS volume.
• Node 2: Running on a Raspberry Pi with a Docker configuration file, also using the shared NFS volume.

Steps to Deploy

Step 1: Prepare the NFS Server

On your NFS server, create directories for AdGuard Home:

• /path/to/nfs/adguard: For configuration files.
• /path/to/nfs/adguard/primary: For AdGuard Home's primary working directory.
• /path/to/nfs/adguard/secondary: For AdGuard Home's secondary working directory.

Ensure these directories have proper permissions to allow Docker Swarm nodes and the Raspberry Pi to read and write.

Step 2: Define the docker-compose.yml File for Node 1

Below is the Docker Compose file for the Swarm node:

services:
  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    ports:
      - 53:53/tcp
      - 53:53/udp
      - 784:784/udp
      - 853:853/tcp
      - 3131:3131/tcp
      - 8443:443/tcp
    volumes:
      - nfs-adguard-primary:/opt/adguardhome/work
      - nfs-adguard-conf:/opt/adguardhome/conf
    restart: unless-stopped
    deploy:
      placement:
        constraints: [node.role == worker]

volumes:
  nfs-adguard-conf:
    driver: local
    driver_opts:
      device: :/path/to/nfs/adguard
      o: addr=<nfs-server-ip>,nolock,soft,rw,nfsvers=4
      type: nfs
  nfs-adguard-primary:
    driver: local
    driver_opts:
      device: :/path/to/nfs/adguard/primary
      o: addr=<nfs-server-ip>,nolock,soft,rw,nfsvers=4
      type: nfs

Step 3: Deploy Node 1 on Docker Swarm

To deploy the AdGuard Home stack on Docker Swarm:

1. Save the above docker-compose.yml file.

Deploy the stack using the Docker Swarm CLI:

docker stack deploy -c docker-compose.yml adguard

Step 4: Define the docker-compose.yml File for Node 2 (Raspberry Pi)

Below is the Docker Compose file for the Raspberry Pi node:

services:
  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    ports:
      - 53:53/tcp
      - 53:53/udp
      - 784:784/udp
      - 853:853/tcp
      - 3131:3131/tcp
      - 80:80/tcp
      - 8443:443/tcp
    volumes:
      - nfs-adguard-secondary:/opt/adguardhome/work
      - nfs-adguard-conf:/opt/adguardhome/conf
    restart: unless-stopped

volumes:
  nfs-adguard-conf:
    driver: local
    driver_opts:
      device: :/path/to/nfs/adguard
      o: addr=<nfs-server-ip>,nolock,soft,rw,nfsvers=4
      type: nfs
  nfs-adguard-secondary:
    driver: local
    driver_opts:
      device: :/path/to/nfs/adguard/secondary
      o: addr=<nfs-server-ip>,nolock,soft,rw,nfsvers=4
      type: nfs

Step 5: Deploy Node 2 on the Raspberry Pi

1. Save the above docker-compose.yml file on the Raspberry Pi.

Deploy the container using the following command:

docker-compose up -d

Step 6: Verify the Deployment

For Node 1, check the status of your AdGuard Home service:

docker service ls

For Node 2, check the container status on the Raspberry Pi:

docker ps

Step 7: Access the AdGuard Home Web Interfaces

AdGuard Home is accessible via its web interfaces. Open your browser and navigate to:

• Node 1: https://<node1-ip>:8443
• Node 2: https://<raspberry-pi-ip>:8443

Replace <node1-ip> and <raspberry-pi-ip> with the respective IP addresses of the nodes where the services are running. You can log in and configure AdGuard Home from here.

Advantages of This Setup

1. Shared Configuration: All instances share the same configuration, ensuring consistency.
2. Hybrid Deployment: Combines the robustness of Docker Swarm with the flexibility of a standalone Raspberry Pi.
3. High Availability: Ensures the service remains available even if one node goes down.

Troubleshooting

• NFS Mount Issues: Check permissions on the NFS server and ensure NFS is accessible from both the Swarm nodes and the Raspberry Pi.
• Port Conflicts: Ensure the ports used by AdGuard Home are not in use by other services.
• Service Deployment Errors: Inspect logs for detailed error messages.

For Node 1:

docker service logs adguardhome

For Node 2:

docker logs adguardhome

Conclusion

This guide demonstrates how to deploy an AdGuard Home cluster using Docker Swarm and a Raspberry Pi with shared configuration via NFS. This setup is robust, scalable, and ensures high availability. By combining Docker Swarm and a standalone Raspberry Pi, you achieve a flexible and efficient deployment strategy.

Happy ad-blocking!