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

Setup

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.

• If you’re a first timer and want to just get the OS installed, see here.
• Make sure you setup SSH as well.
• Install docker on it.
• Get a repository setup from a reputable host: github, bitbucket, gitlab (learn how to use it if need be)

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 = 8.8.8.8 (or another DNS server you trust)
   4. DNS Server 3 = 8.8.4.4 (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.

How should you Respond to a HTTP DELETE?

If you’re building a RESTful API, you’ll soon come across the scenario where you need to delete some resource, so you make an endpoint with the DELETE verb. Someone calls that endpoint, and you have some options for what to return:

• HTTP 202 – the entity is not deleted but you’ve enqueued the request to delete the item, and the system will get to it.
• HTTP 200 – the entity is deleted and you need to return some entity to the caller (maybe some kind of receipt).
• HTTP 204 – the entity is deleted and there’s nothing to return.

Now onto the final scenario: the entity doesn’t exist. How do you respond? The options are universally argued to be between 204 and 404.

You can get into this situation in a couple of ways:

1. The resource never existed.
2. Multiple requests to delete the resource were sent, which can be for a variety of reasons, race conditions being the one that can’t reasonably be prevented.

When thinking of the difference between 204 and 404, I try to think of what the response code tells the user:

• 204 says “the call was a success: the system does not contain the item you requested for deletion”
• 404 says “the call was not a success: the system did not contain the item you requested for deletion”

When comparing them like that, a 404 doesn’t make sense. It is my contention that the 404 scenario is, instead, vacuously successful, and should be a 204. Whether the data was deleted in a race with another caller, deleted in a previous call that failed to return a response (prompting the client to retry), or succeeded vacuously because the data wasn’t there to begin with, it doesn’t so much matter. The request to have the resource deleted was successful. Whether or not the server had to do work to actually delete anything is irrelevant, and a 404 probably breaks the abstraction that the endpoint’s contract provides.

Those are my thoughts. Hope it helps.