How To Install Pi-hole in A Docker Container

Here’s a step-by-step tutorial on how to install Pi-hole in a Docker container:

Step 1: Install Docker

Make sure you have Docker installed on your machine. You can download and install Docker from the official website: Docker.

Step 2: Pull the Pi-hole Docker Image

Open your terminal and run the following command to pull the official Pi-hole Docker image from Docker Hub:

docker pull pihole/pihole:latest

Step 3: Run the Pi-hole Container

Now, run the Pi-hole container using the following command. Make sure to replace “YourPassword” with the password you want to set for the Pi-hole web interface:

docker run -d \
  --name pihole \
  -p 53:53/tcp -p 53:53/udp \
  -p 80:80 \
  -e WEBPASSWORD="YourPassword" \
  -v "$(pwd)/etc-pihole/:/etc/pihole/" \
  -v "$(pwd)/etc-dnsmasq.d/:/etc/dnsmasq.d/" \
  --dns=1.1.1.1 \
  --restart=unless-stopped \
  pihole/pihole:latest

This command sets up the Pi-hole container with necessary ports, environment variables, and volume mounts.

Let’s break down the flags:

Let’s go through each flag:

-d: Runs the container in the background (detached mode). This allows you to continue using the terminal while the container is running.

--name pihole: Specifies a name for the container, in this case, “pihole.”

-p 53:53/tcp -p 53:53/udp: Maps port 53 for both TCP and UDP protocols. Port 53 is used for DNS, and this mapping allows Pi-hole to receive DNS requests.

-p 80:80: Maps port 80. Pi-hole’s web interface runs on port 80, and this mapping allows you to access the web interface.

-e WEBPASSWORD="YourPassword": Sets the password for the Pi-hole web interface. Replace “YourPassword” with the desired password.

-v "$(pwd)/etc-pihole/:/etc/pihole/": Mounts a volume for Pi-hole’s configuration files. This ensures that your Pi-hole settings persist even if the container is removed.

-v "$(pwd)/etc-dnsmasq.d/:/etc/dnsmasq.d/": Mounts a volume for dnsmasq configuration. Similar to the Pi-hole configuration, this ensures persistence of dnsmasq settings.

--dns=1.1.1.1: Sets the DNS servers for the container. In this example, it uses Cloudflare’s public DNS (1.1.1.1).

--restart=unless-stopped: Configures the container to restart automatically unless explicitly stopped by the user.

pihole/pihole:latest: Specifies the Docker image to use. In this case, it’s the official Pi-hole image from Docker Hub, tagged as “latest.”

Note: if you are using ubuntu or other distribution that uses systemd-resolved, you will get an error. In that case you’ll have to stop and disable it, follow the below steps to do so.

Disable systemd-resolved (only if you get error)

sudo systemctl stop systemd-resolved
sudo systemctl disable systemd-resolved

Now if you ping google.com , it will fail. To fix this real quick, you can edit the /etc/resolv.conf file to add Cloudflare’s DNS. Just open the file using any text editor and add the following line to it,

nameserver 1.1.1.1

Now your machine has DNS. Thus it can ping google.com But, if you want to have ad-blocking on this machine too, then you should change it to your local ip-address later when pi-hole is properly configured.

Step 4: Access Pi-hole Web Interface

Once the container is running, you can access the Pi-hole web interface by opening a web browser and navigating to http://localhost/admin or http://<your_server_ip>/admin. Log in with the password you set in the WEBPASSWORD environment variable.

Step 5: Configure DNS Settings

Follow the on-screen instructions to configure your DNS settings. You may need to update your router’s DNS settings to point to the IP address of the machine running the Pi-hole container.

That’s it! You’ve successfully installed Pi-hole in a Docker container. The container will automatically start on system boot, and you can manage your Pi-hole settings through the web interface.

Pi-hole in A Docker Container