pi-hole and docker-compose

Just to put it all in one place, here’s a quick walkthrough of setting up pi-hole to run on your raspberry pi using docker-compose.

  1. Setup
  2. Create a docker-compose file
  3. Start pi-hole
  4. Configure your network or clients
  5. Update pi-hole


I’ll link some resources here, but I’m expecting you to get this piece settled on your own. These are all very searchable things. The goal after setup is a working pi that you can get files onto, easily.

Create a docker-compose file

In your repository, create 2 files:

  • docker-compose.yml
  • readme.md

In the first file, copy the contents from here (update 03/25/2021: I created a gist for this because the original link went dead), replace the timezone with your timezone, and push the file to the repository.

Start pi-hole

  • SSH into your pi
  • Clone the repository into a folder on the pi
  • Navigate to the folder that you cloned your repository into
  • Uncomment and insert a value for the WEBPASSWORD
  • Execute the following command to create a log file that needs to exist…
> touch ./var-log/pihole.log
  • Execute the following command to start the docker container…
> docker-compose up -d

Docker should pull the image and start the container.

Configure your network or clients

So you’ve got pi-hole running on your network now, but that doesn’t do any good unless the machines on your network are requesting dns lookups from it. In the ideal scenario, you can update your network so that all devices will automatically start calling the pi for dns lookups. I’ll walk you through doing that in Ubiquiti Unifi, because that’s the network I have.

In case you can’t update your network to use a common DNS server, you can find out how to update DNS on most machines here.

Here’s how to do it in Unifi.

  1. Login to your controller
  2. Give your raspberry pi a fixed IP
    1. Clients
    2. Select your pi
    3. Configuration
    4. Network +
    5. Check Use fixed IP address (it should show the address it already has)
  3. Go to Networks > LAN (edit)
  4. Make the following changes:
    1. DHCP Name Server > Manual
    2. DNS Server 1 = the ip of your pi
    3. DNS Server 2 = (or another DNS server you trust)
    4. DNS Server 3 = (or another backup DNS server you trust)

The other DNS servers are there, just in case your pi dies or something like that and you don’t want an outage.

Update pi-hole

Stick the following in the readme.md file that you created before. That way you’ll never forget how to update pi-hole.

  • SSH into your pi
  • Navigate to the folder that you cloned your repository into
  • Execute the following commands, individually (they’ll write some stuff to the terminal) to stop pi-hole, update it, and restart it:
> docker pull pihole/pihole 
> docker-compose down
> docker-compose up -d

That should be everything you need to setup a pi-hole and update it when the time comes.

Hope it helps.