Basics

Pi-hole in a Docker Container

Installing Pi-hole as a Docker container is easy and do serve you well.

Nalle

Nalle

— 4 min read
Share
Pi-hole in a Docker Container
Photo by Taso Katsionis / Unsplash

Installation

You need to have Docker running. I'm using Dockge to control my containers, but you can also use Portainer.

Notes

  • Environment
    • TZ: Set the appropriate timezone for your location (see link of TZ codes),
    • FTLCONF_webserver_api_password: Set a password to access the web interface, or a random password will be issued for you (will be shown).
    • FTLCONF_dns_listeningMode: 'ALL' for volumes to store your data between container upgrades
  • Volumes store your data between container upgrades volumes.
    For persisting Pi-hole's databases and common configuration file locations
    • Custom dnsmasq section, uncomment if you have custom dnsmasq config files that you want to persist. Not needed for most starting fresh with Pi-hole v6.
      If you're upgrading from v5 and have used this directory before, you should keep it enabled for the first v6 container start to allow for a complete migration. It can be removed afterward.
  • cap_add: See link. Required if you are using Pi-hole as your DHCP server, else not needed
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    restart: unless-stopped
    ports:
      - "53:53/tcp"   # DNS Ports
      - "53:53/udp"   # DNS Ports
      - "80:80/tcp"   # Default HTTP Port
      - "443:443/tcp" # Default HTTPs Port. FTL will generate a self-signed certificate
      #- "67:67/udp"   # Uncomment if using Pi-hole as your DHCP Server
      #- "123:123/udp" # Uncomment if using Pi-hole as your NTP Server
      
    environment:
      TZ: 'Europe/London' # Edit to reflect your timezone
      FTLCONF_webserver_api_password: 'a long and complicated password'
      
    volumes:
      - './etc-pihole:/etc/pihole'
      # Custom dnsmasq section
      #- './etc-dnsmasq.d:/etc/dnsmasq.d' # Uncomment if using a custom dnsmasq config
      
    cap_add:
      - NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
      #- SYS_TIME  # Required if you are using Pi-hole as your NTP client to be able to set the host's system time 
      #- SYS_NICE  # Optional, if Pi-hole should get some more processing time

Login

http://<IP of Docker VM>/admin/

Change your random Password

Use docker exec -it <container_name> /bin/bash and issue pihole setpassword
If you are using an environment variable, please change in the .env file or in the environment section.

Using a Locked ISP Router for DNS and DHCP

Many ISP routers are locked, meaning we can not freely set it as we like or set it in Bridge mode. This is a way to fool it.

How it works

If the ISP router DHCP don't have free IP addresses to give, our Pi-hole DHCP will do it.

After setting up your Pi-hole login to your ISP Router and check the subnet and free IP Addresses. You probably have 192.168.1.0/24 or 192.168.0.0/24 or something like that.
Below we use the 192.2.0.0/24 documentation subnet, replace with yours.

Add two DHCP Reservations with two dummy MACs

  • Host Name: blackhole – MAC: aa:aa:aa:aa:aa:aa – Reserved IP Address: 192.0.2.2
  • Host Name: dead-end – MAC: bb:bb:bb:bb:bb:bb – Reserved IP Address: 192.0.2.3
  • Set the DHCPv4 Lease Time to 1–2 minutes
  • Set DHCP range from 192.0.2.2 to 192.0.2.3

Now you can set your Pi-hole as your DHCP server using the 192.0.2.0/24 subnet and use 192.0.2.1 for the Gateway and 192.0.2.100 – 192.0.0.199 as the range.

Other

Block lists

The basic steveblacks list is a good one. Another is the Hagezi/dns-blocklist set.

References

Pi-hole [1] DNS blocklists: Steven Black [2] Hagezi [3]

  1. Note GitHub, getting started docs. For cap_add notes ↩︎

  2. Steven Blacks blocklists GitHub, txt ↩︎

  3. Hagezis blocklists GitHub ↩︎

Read more