After you installed PiHole according to Install PiHole in docker-compose on Ubuntu Server you probably want to run regular updates.

With docker compose you simply could run this:

cd /opt/pihole/
sudo docker-compose stop
sudo docker-compose rm -f
sudo docker-compose pull
sudo docker-compose up -d

thanks to https://stackoverflow.com/a/39127792/7311363

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.