A Complete Guide to Setting Up Pi-Hole on Ubuntu Server with Docker

Pi-hole serves as an effective solution for network-wide ad-blocking and DNS filtering. While it is commonly associated with Raspberry Pi installations, savvy users can also deploy Pi-hole in a Docker container on an Ubuntu server. This guide provides step-by-step instructions on how to set up Pi-hole using Docker on your system.

Installing Docker on Ubuntu Server

To begin, keep your Ubuntu server up to date. Execute the following commands to refresh your package list and install necessary updates:

sudo apt update
sudo apt upgrade

After completing the updates, you will need to install packages vital for Docker setup. Run this command to install them:

sudo apt install apt-transport-https ca-certificates curl software-properties-common

The next step involves downloading the GPG key for the Docker repository. This key is essential for the secure installation of Docker components:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Creating a Pi-hole Docker Compose File

Setting up Pi-hole on Docker is streamlined with the help of a Docker Compose file. This allows for handling multiple configurations easily ahead of time. Below is a template for a standard Docker Compose file:

version: "3"

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp" # Used if you activate DHCP on Pi-hole
      - "80:80/tcp"
    environment:
      TZ: 'America/Chicago'
      WEBPASSWORD: 'PASSWORD'  # Replace with a secure password
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      - NET_ADMIN  # Required for DHCP, not needed otherwise
    restart: unless-stopped

To implement this, first log in to your Ubuntu server via SSH and create the docker-compose.yml file using the touch command:

touch docker-compose.yml

Open the newly created file in the Nano text editor:

nano -w docker-compose.yml

Paste the provided Docker Compose configuration into the file, making sure to update "PASSWORD" with a memorable and secure password. Save your changes by pressing Ctrl + O and then exit by pressing Ctrl + X.

Deploying Pi-hole on Ubuntu Server with Docker

Once your Docker Compose file is ready, launching the Pi-hole container is straightforward. Issue the following command to start the container:

sudo docker compose up -d

Monitor the terminal output for any errors. If successful, the Pi-hole container will run seamlessly on your Ubuntu server. You can access the Pi-hole interface by navigating to:

http://IP-ADDRESS-OF-UBUNTU/admin/

Configuring Pi-hole

After accessing the Pi-hole interface, configure it according to your needs. Below are the key configuration steps.

Setting Up Upstream DNS

Navigate to the “Settings” tab and select “DNS.” Here, you’ll configure upstream DNS servers. The default is set to Google DNS, but you can opt for alternatives such as:

• Cloudflare DNS
• Quad9 DNS
• OpenDNS
• NextDNS

Once you make your selections, save your changes by clicking the “Save” button.

Configuring Adlists

Next, go to the “Adlists” section via the Pi-hole sidebar. This will direct you to the “Adlist group management” area where you can find preset adlists. For most users, the default adlists are sufficient, but you can add some popular options to enhance your protection against ads and tracking:

• Adaway: https://adaway.org/hosts.txt
• Easylist: https://easylist.to/easylist/easylist.txt

Your changes to the adlists are automatically saved as you make additions.

Device Configuration

Having set up the upstream DNS and adlists, it’s crucial to configure your devices to use Pi-hole as their DNS server. For optimal performance, it is recommended to set your router to use Pi-hole as the primary DNS server. This configuration ensures that all devices on your network utilize Pi-hole without needing to adjust settings on each one separately. For detailed guidance on device configuration, visit the official Pi-hole documentation.

With these steps, you now have Pi-hole running on your Ubuntu server with Docker, equipped to provide enhanced ad-blocking solutions across your network.