Introduction
Pi-Hole is a network-wide Ad Blocking based on a DNS filter. It can also act as a DHCP server.
Pi-Hole Installation
Method: 1 (Auto)
Run the following script
wget -qO- https://raw.githubusercontent.com/akkupy/Homelab/main/scripts/install_pi_hole.sh | bash
Method: 2 (Manual)
Folder Setup Script
The first thing we need to do is set up the folder structure.
Run the following script :
wget -qO- https://raw.githubusercontent.com/akkupy/Homelab/main/scripts/pi_hole_dir.sh | sudo bash
Now we need to move into that directory using the following:
cd /home/$USER/pi_hole
We now need to open the docker-compose.yml file using the nano editor.
nano docker-compose.yml
Copy and paste the below Docker-compose example into the docker-compose.yml file.
💡NOTE: Change the TimeZone and Conflicting ports according to your needs.See the example below: Docker-compose example:
version: "3" # More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/ services: pihole: container_name: pihole image: pihole/pihole:latest # For DHCP it is recommended to remove these ports and instead add: network_mode: "host" ports: - "53:53/tcp" - "53:53/udp" - "67:67/udp" # Only required if you are using Pi-hole as your DHCP server - "4000:80/tcp" environment: TZ: 'America/Chicago' # WEBPASSWORD: 'set a secure password here or it will be random' # Volumes store your data between container upgrades volumes: - './etc-pihole:/etc/pihole' - './etc-dnsmasq.d:/etc/dnsmasq.d' # https://github.com/pi-hole/docker-pi-hole#note-on-capabilities cap_add: - NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed restart: unless-stopped
Once you have done that press “Ctrl + X” then Y to save and “Enter” to exit the nano editor.
To deploy the dockers run the following command:
sudo docker-compose up -d
This will take some time to finish.
Once complete you can check that the docker containers exist by typing the following:
sudo docker ps
Or you can check in Portainer by logging in via your browser and navigating to “Containers“.
If you see any problems like “unhealthy” Please restart the container and all should be well.
Post Installation
Admin Password
Once deployed, open the container logs, disable Auto-refresh logs
so you can scroll freely and look for Assigning random password: XXXXXXXX
to get the Admin password.
You can set a new password by opening the Console through Portainer and typing pihole -a -p
and entering the password when requested.
You can find more commands to run here.
With the admin password, go to http://<Raspberry IP>:4000/admin
to access the Pi-Hole web interface and log in.
(Optional): Configure Reverse Proxy using the documentation here
Change the DNS settings Interface listening behaviour to "Listen on all interfaces, permit all origins", if using Docker's default bridge
network setting. (This can also be achieved by setting the environment variable DNSMASQ_LISTENING
to all
)
Setting Mainstream DNS
Go to Settings
and select DNS
on top.
On the left-hand side, you can select any one of the known DNS providers or insert a custom one on the right-hand side.
You can also set Use Conditional Forwarding
for the Pi-Hole to ask your DHCP server for the hostname of the local IPs. For this to work, define your local network CIDR (I've used 192.168.0.0/16 that covers all possible subnets within 192.168.x.x range), then insert the IP of your DHCP server (normally your router) and optionally a local domain name.
If you're having loop issues with your router, then you might want to disable this option.
Point your router or device to Pi-Hole
As each router is different to configure, I'm not going to detail here how it's done. However, you can point your router DNS to Pi-Hole IP (Raspberry IP) and it will use it as the main DNS, blocking any request included on its blacklist.
Optionally, you can set each device to use a custom DNS and insert the IP of your Raspberry.
You can also refer to the pi-hole router setup documentation for more information.
Adding more Ad lists
You can add more lists through Group Management
-> Adlists
. Then just add the list you want to use.
You can visit The Big Blocklist Collection if you want to add more.