Installing Pi-hole on Raspberry pi

Even though we can install pi-hole directly on raspberry pi. In this post I will show how to run it in docker container. So we have to have docker installed on raspberry pi. First of all please read the previous post where we installed docker on raspberry pi. To run pi-hole we will create a docker container using pi-hole image.

Create a directory in your raspberry pi, like below

mkdir docker-test
cd docker-test
touch docker-compose.yml
nano docker-compose.ymlCode language: CSS (css)

Now paste the code in the docker-compose.yml

# 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
      - "80: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-stoppedCode language: PHP (php)

After this save the docker-compose.yml file. Pressing Ctrl+o in nano and Ctrl+x to exit nano. Then run the following command to run the pi-hole container, make sure while running the command that you are in same directory where yml file is located, otherwise an error will be shown “no configuration file present” or similar.

sudo docker compose up -d

This will download the pi-hole image (if not already donwloaded), create a container based on it and run it. However you can have a conflict of ports and this might not run. For example I had a apache server running on port 80 therefore there was a conflict. So you can change the port section in the yml file as below

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
      - "8080: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
Code language: PHP (php)

I have changed port 80 to 8080 so that docker listens on port 8080 but internally the pi-hole will be made to be believe that it is listening on port 80. Furthermore I have commented port 67 because I do not want pi-hole to be used as dhcp server.

To stop the pi-hole container, you can type the command

sudo docker stop pihole

pihole is the also name of the container, that we created earlier.

To list name of the containers you can type

sudo docker ps -a

This will show all containers , running or stopped.

Pihole URL acesss and username, password

Once the container is running we can use following url to access the pihole. If you had changed port to 8080 then use the port accordingly in the url, otherwise you can avoid mentioning port in the url. For example if your raspberry pi ip address is 192.168.18.10 then the Url looks like below

http://192.168.18.10:8080/admin

http://192.168.18.10/admin

If pihole asks password in the login page

if the pihole asks the password in the login url page or admin page, you can reset it as follows by giving the command to pihole. Since pihole is running in the container and not accessible outside the container, therefore we will issue the command to pihole thourgh docker as follows. Make sure container is running before this command, otherwise it makes no sense.

docker exec -ti <name_of_your_container> pihole -a -pCode language: HTML, XML (xml)

Since out container name is also pihole we run it like this. Note, we have to use sudo before the command

docker exec -ti pihole pihole -a -p

This will reset the password, you can give a new password and login to the url again.

Adding DNS to the router

After having setup pihole, we need to point the DNS server of router to the pihole which is your raspberry pi ipaddress. In otherwords, now your raspberry pi is acting as a DNS server. Depending on your router you have first login to the router configuration page. open your browser and input the login url. You can check the router admin page url, username and password on your router’s back. Once you login , you can find appropriate menu to enter the DNS address. You you use your Raspberry pi ip address in that field and save it. You may have to restart the router. To verify if your DNS server is hitting, you have to login to pihole administration page whose URL was given above and it will show you the details of clients. It is suggested that you also enter same value in the secondary DNS server field.

Caveats using Pi-hole

Android google chrome browser problem

I had problem with android 11 doing browsing so I fixed it as follows. If on android phone chrome browser is often showing DNS error and not browsing an allowed website. You should open the app list in android and clear the cache and storage of chrome. Furthermore you can use firefox as default browser of android.

Some devices by pass Pi-hole (due to Ipv6 or custom dns)

Some useful commands are below

sudo resolvectl flush-caches // to flush local dns caches
sudo resolvectl statistics   // to check stats of dns cache
dnslookup domain-name        // to check ip address returned from default dns server
dnslookup domain-name ip-address-of-dns //to explicitly check results returned by the given dns serverCode language: JavaScript (javascript)

I had added some custom domains representing my own devices on the local network, so that I do not have to type LAN ips, for example mypi.com, myzbook.com etc. However I noticed that some machines were occasionally hitting the pihole DNS and sometimes not, and therefore getting real ip address of the above domains. You can try following resolutions.

Firstly, on your machine where your domain is not hitting the pihole, make sure you have no custom DNS servers and DHCP is automatic in your network connection. This way the router assigns the DNS server it has in its configuration to the connection.

I had this custom DNS in my connection which I had to change to automatic

Secondly you may have to disable IPV6 publishing or announcement by your router. In my case I had to disable both enable DHCPv6 Server and Enable Router Advertisement. Before disabling them my network/wifi connection in Ubuntu 22.01 was displaying this

Both of these were enabled by default and I had to uncheck/disable both of the settings below to let DNS 6 disappear from my network connection. You can manually do it as well on each such device but if your router is not publishing IPV6 DHCP server and route advertisement then it works for all devices in general.

After updating the router settings, refresh your network connected or better yet restart router.

DNS resolution not available

If you have problem updating gravity ( a pi-hole database which is updated regularly to block new domains) and you get an error like “Dns resolution not available then you can add a dns: -127.0.0.1 entry in the docker-compose.yml file and reissue the command to recompile, run as given above. After update the docker-compose.yml will look like this

# 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
      - "8080:80/tcp"
    environment:
      TZ: 'America/Chicago'
      # WEBPASSWORD: 'set a secure password here or it will be random'
    # Volumes store your data between container upgrades
    
    dns:
       - 127.0.0.1

    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
Code language: PHP (php)