Hey friends! If you already deep into docker and just want an example
docker-compose.ymlto work from for your project, skip to the end or download it from my Github repo
I've been thinking for a long time that I wanted to setup my own Pi-hole for some ad blocking and maybe some additional sketchy website blocking in my home. Now that the kids are getting older and have access to chrome books and full-on computers that let them climb the heights of internet knowledge, I want to at least provide some protection from the skummy depths and darkness the internet contains. Or at least delay ad companies from creating a total picture of their personality before they can even drive.
And if that was all I wanted to do, this would have been a quick after-work project to get up and running with a few other fidley network bits to adjust for DNS and DHCP. But I also want to update my home wifi and really need an updated UniFi controller that I wanted back behind my firewall. And those should both be able to run on a Raspberry Pi just fine. And here, like a good DevOp, I begin to completely overengineer the solution...
First, I don't want to have to deal with big install processes and application files located all over the place. I definitely don't want to have to remember all the /etc/config files and settings to get started. And I probably need some sort of reverse proxy to make sure the websites work properly. I know! Docker! If I use
docker-compose I should be able to get everything I need configured in a single text file, stored in my home directory, and everything should run and reboot automagically.
The great thing is, all of the information to do this exists on-line, unfortunately, not all in the same place. So after hours of searching and typing and tweaking, I wanted to offer a single resource to get this all up and running for the next person.
This guide is making some assumptions about your initial setup and skills:
- Raspberry Pi 3 or later (arm64)
- Imaged with a server or Lite OS image (all console no GUI)
- Terminal text editor of choice installed/configured
- Pi's networking is all configured in its final state. Static IP, interfaces, DNS fallbacks, the whole bit.
docker-composeare installed and the docker service is registered and running
- Your user (either
pior the custom user of your choice) is added to the docker group so you can run docker without root/sudo
So if you've got all that, you should be ready to start drafting your compose file.
Knee Deep in YAML
I started at the official Docker pi-hole repository which gives some great examples and sample configurations. I'm going to go through each step of configuration for thoroughness, but if you just want a completed
docker-compose.yml, skip to the end of this article and note the comments about where to edit with your personal information. So first, we want to just go through getting the
pihole service running:
The above is sufficient to get you going with just pihole. From here a nice
docker-compose up -d will launch pihole detached from your console and you could login from your web browser from there. There's nothing too tricky here, but ensure you set your
WEBPASSWORD environment variables to your liking. But only getting
pihole running is not why we're here, so next we want to configure a second container service for the UniFi.
I found the info for this one in a linuxserver.io repository on github. Their example was a v2.x docker compose file, but very little had to be done to update it for version 3:
If you took a look at the linked repository, you'll notice that I excluded a few settings and tweaked it a bit here and there. Largely this was due to compatibility issues that simply don't exist anymore. Nothing here is special, there are no install-specific variables that need to be configured as all of the UniFi config is done through the web interface.
Here's where the tricky bits start. If you've explored the pi-hole/docker-pi-hole git repository you'll find this great example of a configuration complete with reverse proxy for hosting multiple sites. But the existing
jwilder/nginx-proxy only has an image on Docker Hub for amd64 architecture. After digging around a bit, it looks like I wasn't the first to run into this, and thankfully Budry took Jwilder's existing work and rebuilt the images on multiple architectures, so now we can start to tie this all together.
First, I want to get the proxy container info entered:
You'll notice Nginx needs to bind to ports 80 and 443 which is going to conflict with the pihole config earlier, we'll address that in a second. Most importantly, though, you need to make sure your
DEFAULT_HOST is set to your Pi-hole. This is important for some Pi-Hole functionality.
Next, let's adjust the Pi-Hole config accordingly, and add some environment variables to help direct the reverse proxy:
Not a lot has changed, but what has is important. First note the ports adjusted. We're now mapping
8053:80 to free up host port 80, and
9443:443 to free up 443. I used the 9000 range instead of the standard 8000 since
8443 is needed for UniFi.
Next, you'll see the aditional environment variables
VIRTUAL_PORT these let docker-gen know how to configure the proxy for nginx. The host could be named as you want (if for some reason you don't like
pihole) but port 80 is important.
Finally, a whole section has been added under
extra_hosts: this is where you're going to list
hostname FQDN:IP.Address for each host (beyond nginx) you want to spin up in the docker environment. It's listed here as this is our Default Host. For our purposes, we need the primary domain and the pihole and unifi subdomains.
And with that, we can wrap it up with the changes needed for the unifi-controller bits:
This one is even easier with the changes you might have predicted at this point,
VIRTUAL_PORT are all familiar from the above and we make the addition of
VIRTUAL_PROTO since unifi wants encrypted traffic and otherwise will try to connect via http which will make unifi sad.
The Completed YAML File
Now for what you might be waiting for, the completed
docker-compose.yml (This one is sanitized and full with commentary for those skipping right to this point):
At this point, you can run
docker-compose up -d and with a little patience you'll have all your services up and running on your Pi. It freaked me out a couple times where I thought the UniFi controller was broken and not working, but it looks like it just takes a little longer to get started than Pi-Hole. So give it a few minutes before you try to browse the web portals, but once all the services are up you should be able to navigate in your web browser using the FQDNs.
Because your home domain is probably an invalid TLD, you'll likely have to type a full URL like
https://unifi.domain.tld to avoid your browser's search functionality. If they don't resolve, it's probably because you're not using your pihole as your DNS server yet. Note: the UniFi controller might be a little wonky without directing it to 8443 since that's the expected port to communicate on. I've been trying to get it to play a little nicer, but haven't gotten there at time of writing. I'll update if I do get it all working 100%.
With this, you're able to use all your services! If you have any issues with this or find any way to improve on it I'd love to find out; leave a note on my github repo!
P.S. Advanced Networking
This is where that note about
host mode networking in the
pihole container config becomes relevant. For the Pi-hole server to recieve DHCP requests, it generally needs to be wide open to requests and broadcasts, but since it's packed into docker's virtual network, this can creates challenges and since we're using the reverse proxy and hosting multiple services on docker, we can't just attach the entire network interface from the host Pi without causing conflicts. It's possible this will all work without changes, but if not, we need to tweak the network to ensure DHCP requests are making their way to your
The answer here is that you'll need to configure a DHCP relay on your network. This is a service that will relay the DHCP request to the specific IP that should be answering. This is done to allow a DHCP request to be answered by a server outside of the requestor's broadcast domain. How you do this depends on the equipment you have available. If your router is sufficiently advanced it may have this as a configurable setting otherwise, it is possible to configure another small docker service to act as a relay. Since I have a Ubiquiti Edge Router X, all I had to do was login and make a two-line config change and save it:
Here, the IP address used is the same as the static IP address of your Pi being used in all the configurations previously.
So if you were having any DHCP issues, those should all be solved with the relay.