This article will explain, in detail, how to use your Raspberry Pi as a dedicate Pi Hole appliance in your home network. There are many ways you can install Pi Hole. The official Pi Hole GitHub page recommends running a bash script. Another popular method is to use a docker image from docker hub.
If you haven’t used Docker before, this should be a good eye-opener as you will use a little of everything. If you get stuck, let us know in the comments at the end of this article. Though there should be plenty of resources you can search for online, so likely your question has been answered somewhere already.
Step 0 – Installing Raspberry Pi OS onto a micro SD card
Note to those that received a free Raspberry Pi from ABQLUG over this project… You can start from Step 1. We already did Step 0 for you!
Follow this tutorial to install a Raspberry Pi OS image onto a micro SD card:
Step 1 – Setting up Raspberry Pi OS
The first time you plug in your Raspberry Pi into a monitor and power it on, it should show on the screen that the SD card is expanding. Please leave the Raspberry Pi on and uninterrupted during this time.
After some about a minute or two you should see a box that says: Welcome to the Raspberry Pi Desktop.
At this point, it’s just a matter of choosing the system settings and clicking on next.
Country: United States
Checkmark: Use English language
Checkmark: Use US keyboard
Choose a new password (uncheck hide password if you want)
When the installer asks you if there are black bars around the screen; if you see black bars around every edge of the display, then checkmark the “This screen shows a black border around the desktop” option and proceed.
If you are going to the Raspberry Pi with wifi. You can set that up now. Or click on skip if you plan on using an Ethernet based setup.
The last step will ask if you want to update. It’s recommended to do that now. Unless you are on a time crunch. You can always update later. It took around 17 minutes to download and install the updates from a 10 Mbps DSL connection.
You will want to reboot once you are done.
After the reboot, you will want to give the RPi a static IP since it will act as a DNS server.
There are many ways to tackle this. Since my home router serves DHCP on my network, I ended up telling my home router what IP address to assign the Raspberry Pi based off of it’s MAC address. I would include instructions on how to do this, but every router is going to have it’s own way.
If you are unsure on how to tell your home router how to give your Raspberry Pi a static IP address, then you can just configure the Raspberry Pi to do it.
Open the Terminal application and type this command to open /etc/dhcpcd.conf with nano.
If you have never used nano before; once you want to exit and save your additions, you can close and save by hitting (Ctrl+x) then hitting (Y) and then (Enter). Typing (N) instead will close without saving anything.
sudo --edit /etc/dhcpcd.conf
The dhcpcd.conf file has many options, you can leave them alone and add the following at the end.
Example static IP configuration, again the network addresses will vary depending on your home network.
interface eth0 static ip_address=192.168.1.250 static routers=192.168.1.1 static domain_name_servers=127.0.0.1 126.96.36.199
Now reboot to make sure you are using the static IP address.
Once the reboot is finished, check to see if your Raspberry Pi is using the correct IP address.
You will want to check either eth0 or wlan0 depending on if you are using an Ethernet cable or Wi-Fi.
ip address show
Now that you are using a static IP address, make sure all of the software is up-to-date before installing new software.
sudo apt update sudo apt dist-upgrade
If there are any kernel or any other special updates, then it will ask you to reboot. I usually recommend rebooting after any updates anyways.
Step 2 – Installing docker and docker-compose
Before we can use docker, we will need to add our user account to include group permission from the docker group.
This is necessary so we can run docker without root privileges .
You can use the variable $USER as this will work regardless of what you changed your username to.
sudo usermod --append --groups docker $USER
Now we need to install docker. To the Raspberry Pi OS repository, docker is referred to as docker.io.
Since we need both docker and docker-compose it is easier to install both through the Raspberry Pi OS repository. You could use docker from snapcraft as that is a newer version. But installing docker-compose is not as easy. There is a way to install the docker-compose package from the Raspberry Pi OS repository then remove docker.io and install the snap version of docker. But that is not going to be covered here.
For now, if you install docker-compose through apt, that will also install docker as well.
sudo apt update sudo apt install docker-compose
Once installed, see if docker is working.
If that command did not show you the current version of docker, then reboot and re-run the docker –version command.
Step 3 – Setting up the docker-compose.yaml file
Once you verified that docker is running, proceed by making a new directory for Pi-Hole. Then enter the new directory. The name and location of the directory is up to you.
mkdir pihole-docker cd pihole-docker
Now that you are in your Pi-Hole directory, let’s make the docker-compose.yaml file.
The docker-compose.yaml file will basically give docker-compose a “playbook” to execute and setup docker into a certain environment.
This specific docker-compose.yaml file will tell docker:
- Call the new container: pihole. And will install the latest pihole image from docker hub.
- Open the firewall to allow 53/tcp, 53/udp, 67/udp, 80/tcp, and 443/tcp.
- Tell the docker environment what timezone you are in.
- Make two folders and mount them to the docker container.
- Add DHCP capabilities (although additional configuration is needed if you want this Docker container to also serve DHCP on your network and is not covered in this tutorial)
- Tell docker to restart the container if it crashes, without asking. Unless you specifically stop the container.
Copy and paste this docker-compose.yaml example file, the only thing you will need to edit is the timezone. Please copy everything, including any whitespace.
Use this timezone: TZ: ‘America/Denver’
Note: with .yaml files, whitespace matters.
If you have never wrote anything in yaml before, then you might want to read this if you need more information. Just understand that whitespace has a use in yaml, don’t try and fight it.
In nano, if you want to exit and save your additions, you can close and save by hitting (Ctrl+x) then hitting (Y) and then (Enter). Typing (N) instead will close without saving anything.
Step 4 – Starting Pi-Hole using docker-compose
If the docker-compose.yaml file was written correctly, then should not get any error messages when you run this next command.
If there is an error, it should show up in red. Otherwise, if you see scrolling text, it is likely docker downloading images, and setting up Pi-Hole for use.
Once it looks like Pi-Hole is done being setup, use Chromium on the Raspberry Pi itself and go to: http://localhost/admin/
To login, you will need to set an admin password. At some point the output from docker-compose will actually show you the password once, but it’s really easy to miss it. Plus it’s random.
In a different terminal, you can run this command to generate new Pi-Hole login credentials.
docker exec -it pihole sudo pihole -a -p
If you prefer to have shell access first before typing in that command, then you may do this instead:
docker exec -it pihole /bin/bash sudo pihole -a -p exit
To stop docker, type this once: (Ctrl+c)
Once you verified that Pi-Hole is functional, you can then setup Pi-Hole to run in the background as a daemon. Running Linux containers as a daemon usually implies that it will restart after a reboot. And that would be the case here, we tested it.
docker-compose up -d
That’s it! You know have Pi-Hole running from a Linux container using docker-compose.
Step 5 – Using Pi-Hole
Once you verified that Pi-Hole is running, you can now point your devices to use the new DNS server.
There are multiple ways to do this, the best way to do this is to do this on your DHCP server (typically a home router). Although you can do this on each of your internet connected devices.
If you have never changed the which DNS server your computer uses, then it might be best to Google for it. For example: “Change DNS on Samsung TV”, “Change DNS on Ubuntu 20.04”, “how to change DNS on iPhone”.
Updating Pi-Hole using docker-compose
If you want to update Pi-Hole, do this in the same folder as your docker-compose.yaml file for Pi-Hole:
docker-compose down docker-compose pull #This command will pull down the latest Pi-Hole image from Docker Hub docker-compose up -d docker image prune #Only do this if you want to remove old images
This will give you verbose information when you startup docker-compose.
cd pihole-docker docker-compose up -d -V
This will reconfigure Pi hole.
docker exec -it pihole pihole reconfigure
This will debug Pi hole.
docker exec -it pihole pihole debug