Overview
This will document how to install PiHole on an Ubuntu server. PiHole will run in docker-compose with couple including some volumes from the host, so data could be stored during updates. The docker container for pihole should be is ephemeral.
Base Installation
the following steps are done according to pi-hole/docker-pi-hole
Run this steps:
-
Install docker compose installed on yourserver.example.com with sudo apt install docker-compose
-
For the following use install folder /opt/pihole
-
create docker-compose.yaml in /opt/pihole/
, below is the final version incl the volumes which are added later:
* version: "3"
# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
pihole:
container_name: pihole
hostname: yourserver-pihole
image: pihole/pihole:latest
ports:
- "53:53/tcp"
- "53:53/udp"
- "67:67/udp"
- "80:80/tcp"
- "443:443/tcp"
environment:
ADMIN_EMAIL: 'pihole@example.com'
DNS1: '9.9.9.9'
DNS2: '1.1.1.1'
PIHOLE_BASE: '/opt/pihole'
TZ: 'Europe/Zurich'
WEBPASSWORD: '...'
# Volumes store your data between container upgrades
volumes:
- './etc-pihole/:/etc/pihole/'
- './etc-dnsmasq.d/:/etc/dnsmasq.d/'
- './letsencrypt:/opt/letsencrypt/'
- './letsencrypt/lighttpd-external.conf:/etc/lighttpd/external.conf'
- './fakewebroot/.well-known:/var/www/html/.well-known'
# Recommended but not required (DHCP needs NET_ADMIN)
# https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
cap_add:
- NET_ADMIN
restart: unless-stopped
-
You now can start it with with: docker-compose up --detach
-
You now can connect to http://yourserver.example.com/admin, make sure you don't login with the defined WEBPASSWORD
, your conneciton isn't encrypted yet.
Certificate with Let's Encrypt
The Admin interface isn't encrypted yet, therefore we want to run the let's encrypt (certbot) on the host machine.
Below was done with information from https://discourse.pi-hole.net/t/enabling-https-for-your-pi-hole-web-interface/5771
- We first create a folder
/opt/pihole/fakewebroot
and /opt/pihole/letsencrypt
.
- Above we already added two volumes:
./letsencrypt:/opt/letsencrypt/
to copy the combined.pem and fullchain.pem in
./fakewebroot/.well-known:/var/www/html/.well-known
which will be used by certbot for to safe the challenge
- With this we can run the following command to get the initial certificate:
sudo certbot certonly --webroot /opt/pihole/fakewebroot/ -d yourserver.example.com
- Lighttpd needs a combined.pem which is not automatically created by certbot, so merge them to the letsencrypt folder in our pihole directory. Further copy the fullchain:
sudo cat /etc/letsencrypt/live/yourserver.example.com/privkey.pem /etc/letsencrypt/live/yourserver.example.com/cert.pem > /opt/pihole/letsencrypt/combined.pem
- create a lighttpd-external.conf file in the letsencrypt folder, the file was already added via volumes in the beginnen, but here again:
- Add file with volume command
./letsencrypt/lighttpd-external.conf:/etc/lighttpd/external.conf
-
Add the following to the lighthttpd-external.conf
, make sure you have the correct file names for ssl.pemfile
and ssl.ca-file
:
$HTTP["host"] == "yourserver.example.com" {
# Ensure the Pi-hole Block Page knows that this is not a blocked domain
setenv.add-environment = ("fqdn" => "true")
# Enable the SSL engine with a LE cert, only for this specific host
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/opt/letsencrypt/combined.pem"
ssl.ca-file = "/opt/letsencrypt/fullchain.pem"
ssl.honor-cipher-order = "enable"
ssl.cipher-list = "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"
ssl.use-sslv2 = "disable"
ssl.use-sslv3 = "disable"
}
# Redirect HTTP to HTTPS
$HTTP["scheme"] == "http" {
$HTTP["host"] =~ ".*" {
url.redirect = (".*" => "https://%0$0")
}
}
}
Renew Certificate Automatically
In the section before we already added the well-known folder /opt/pihole/fakewebroot/
and it is already added as volume in docker-compose.yaml
We now need a post action for the timer renewing, create a post hook file. Add the file with
sudo vim /etc/letsencrypt/renewal-hooks/post/redeploy-docker.sh
With this content:
cat /etc/letsencrypt/live/yourserver.example.com/privkey.pem /etc/letsencrypt/live/yourserver.example.com/cert.pem > /opt/pihole/letsencrypt/combined.pem
cat /etc/letsencrypt/live/yourserver.example.com/fullchain.pem /etc/letsencrypt/live/yourserver.example.com/cert.pem > /opt/pihole/letsencrypt/fullchain.pem
/usr/bin/docker-compose -f /opt/pihole/docker-compose.yaml down &>/dev/null
/usr/bin/docker-compose -f /opt/pihole/docker-compose.yaml up --detach &>/dev/null
And make it executable
sudo chmod +x /etc/letsencrypt/renewal-hooks/post/redeploy-docker.sh
This will copy the new certificate in to the correct folder and ensures, the docker container es restarted, so it will have the new ceritificate.
You can test whether your script works properly with a dry-run
sudo certbot renew --dry-run
If docker ps
shows a new container id after that, the container was restarted successful.
With sudo openssl x509 -noout -text -in /opt/letsencrypt/combined.pem | grep Validity -A3
you will see, whether the new certificate was copied correctly (doesn't really work shortly after the installation, because you have no new certificate)
Usage
Now you can use the IP address of yourserver.example.com as you DNS server address.
You can now use https://yourserver.example.com/admin/ to check your server.