How to Install Pi-hole with Docker Compose on Ubuntu

Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, intercepting ad-serving domain requests and blocking them before they reach your devices. It’s a powerful tool for enhancing your network’s privacy and reducing bandwidth consumption by preventing unwanted ads, tracking, and telemetry services. Installing Pi-hole using Docker Compose on an Ubuntu system provides a convenient and scalable way to manage the service, especially if you’re already running other Docker-based services.

This guide will walk you through the steps to install Pi-hole with Docker Compose on Ubuntu.

Prerequisites

Before starting, ensure you have the following prerequisites ready:

1. Ubuntu Server: A server or virtual machine running Ubuntu 18.04 or later.
2. Docker: Docker must be installed and running on your Ubuntu server.
3. Docker Compose: Docker Compose must also be installed.

Step 1: Create a Docker Compose File

To begin, we need to create a Docker Compose file that defines the Pi-hole service. Docker Compose simplifies the process of managing multi-container Docker applications, making it easier to configure and manage services like Pi-hole.

1. Create a directory for Pi-hole:

mkdir ~/pihole
cd ~/pihole

2. Create the Docker Compose file:

Create a docker-compose.yml file inside the directory:

vi docker-compose.yml

3. Add the Pi-hole service configuration:

Paste the following content into the docker-compose.yml file:

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "67:67/udp"
      - "9988:80/tcp"
    environment:
      TZ: 'Europe/Sofia'
      WEBPASSWORD: 'parola'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      - NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
    restart: unless-stopped
networks:
  default:
    name: sites
    external: true

Explanation of the Docker Compose Configuration:

1. Service Definition:

• pihole: This defines the service name, which is pihole in this case.

2. Container Name:

• container_name: pihole: This sets the name of the Docker container to pihole.

3. Image:

• image: pihole/pihole:latest: This specifies the Docker image to use. The latest tag ensures that the most recent version of Pi-hole is used.

4. Ports:

• ports:: Defines the port mappings from the host to the container.
  • "67:67/udp": Maps port 67 (used for DHCP) from the host to the container. This is needed if Pi-hole is used as a DHCP server.
  • "9988:80/tcp": Maps port 9988 on the host to port 80 on the container, which is used by the Pi-hole web interface. This allows you to access the Pi-hole admin interface via http://<host-ip>:9988/admin.

5. Environment Variables:

• environment:: Sets environment variables inside the container.
  • TZ: 'Europe/Sofia': Configures the timezone to Europe/Sofia.
  • WEBPASSWORD: 'parola': Sets the web interface password to parola.

6. Volumes:

• volumes:: Mounts directories from the host into the container for persistent storage.
  • './etc-pihole:/etc/pihole': Maps the host directory ./etc-pihole to /etc/pihole in the container, storing Pi-hole configuration data.
  • './etc-dnsmasq.d:/etc/dnsmasq.d': Maps the host directory ./etc-dnsmasq.d to /etc/dnsmasq.d in the container, storing DNS and DHCP configuration.

7. Capabilities:

• cap_add:: Adds additional Linux capabilities to the container.
  • NET_ADMIN: This capability is required for Pi-hole to manage network interfaces, necessary if Pi-hole is used as a DHCP server.

8. Restart Policy:

• restart: unless-stopped: Ensures that the container automatically restarts unless it has been explicitly stopped by the user.

9. Networks:

• networks:: Defines the network configuration for the service.
  • default:
    • name: sites: This names the default network sites.
    • external: true: Indicates that this network is managed outside of the Docker Compose file. You must create it manually if it doesn’t exist.

Considerations and Next Steps:

• External Network (sites): Since you are using an external network named sites, make sure this network exists before running the Docker Compose file. You can create it using:

docker network create sites

• DHCP Usage: The NET_ADMIN capability is only required if you’re using Pi-hole as a DHCP server. If not, you can remove the cap_add section.
• Web Interface Port: Access the Pi-hole admin interface via http://<your-host-ip>:9988/admin based on the port mapping you’ve set up.

This configuration provides a secure and flexible setup for running Pi-hole on your network using Docker Compose. Ensure you have the necessary network setup and verify that the volume paths are correctly configured on your host system before deploying this setup.

Deploy Pi-hole with Docker Compose

Now that you have your Docker Compose file and directories ready, it’s time to deploy Pi-hole.

Start Pi-hole using Docker Compose:

docker-compose up -d

The -d flag runs the container in detached mode, allowing it to run in the background.

2. Verify the container is running:

docker ps

You should see the pihole container listed, indicating that it’s running correctly.

Configure Pi-hole

Once Pi-hole is running, you can access the web interface to complete the setup and manage its settings.

1. Access the Pi-hole web interface:Open a web browser and navigate to http://<your-server-ip>/admin. Replace <your-server-ip> with the IP address of your Ubuntu server.
2. Log in using the password:Use the password you set in the docker-compose.yml file to log in.
3. Update Pi-hole settings:Once logged in, you can customize settings, such as blocklists, and DNS configurations, to suit your needs.

Monitor and Maintain Pi-hole

With Pi-hole running, you’ll want to monitor its performance and update it regularly.

1. Monitor Pi-hole:The web interface provides a dashboard with statistics on blocked domains, client queries, and more. Regularly check the dashboard to ensure Pi-hole is functioning correctly.
2. Update Pi-hole:To update Pi-hole and its Docker image, follow these steps:
   • Pull the latest Pi-hole image:

docker-compose pull

• Restart the Pi-hole service:

docker-compose down
docker-compose up -d

1. his ensures you’re running the latest version with any security patches or new features.
2. Backup Pi-hole configurations:Regularly back up the directories mounted to the container (~/pihole/pihole and ~/pihole/dnsmasq.d) to retain your settings in case of a failure.

Conclusion

Installing Pi-hole with Docker Compose on Ubuntu is a straightforward process that provides you with a robust network-wide ad-blocking solution. By following this guide, you’ve deployed Pi-hole in a scalable and manageable way using Docker Compose. With Pi-hole, your network will benefit from reduced ads, enhanced privacy, and a smoother browsing experience. Regular maintenance and monitoring will ensure that Pi-hole continues to protect your network effectively.

Thank you for reading the article! If you found the information useful, you can donate using the buttons below:

Donate ☕️ with PayPalDonate 💳 with Revolut