Skip to content

Docker

The easiest way to get up and running with Pi-hole on Docker is to use our quick-start docker-compose.yml template.

Copy the below Docker Compose example and customize as needed

# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      # DNS Ports
      - "53:53/tcp"
      - "53:53/udp"
      # Default HTTP Port
      - "80:80/tcp"
      # Default HTTPs Port. FTL will generate a self-signed certificate
      - "443:443/tcp"
      # Uncomment the below if using Pi-hole as your DHCP Server
      #- "67:67/udp"
    environment:
      # Set the appropriate timezone for your location from
      # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, e.g:
      TZ: 'Europe/London'
      # Set a password to access the web interface. Not setting one will result in a random password being assigned
      FTLCONF_webserver_api_password: 'correct horse battery staple'
      # If using Docker's default `bridge` network setting the dns listening mode should be set to 'all'3
      FTLCONF_dns_listeningMode: 'all'
    # Volumes store your data between container upgrades
    volumes:
      # For persisting Pi-hole's databases and common configuration file
      - './etc-pihole:/etc/pihole'
      # For persisting custom dnsmasq config files. Most will not need this, and can be safely removed/commented out
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      # Required if you are using Pi-hole as your DHCP server, else not needed
      # See Note On Capabilities below
      - NET_ADMIN
    restart: unless-stopped

Run docker compose up -d to build and start Pi-hole (on older systems, the syntax here may be docker-compose up -d)

The equivalent command for docker run would be:

docker run --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -p 443:443/tcp -e TZ=Europe/London -e FTLCONF_webserver_api_password="correct horse battery staple" -e FTLCONF_dns_listeningMode=all -v ./etc-pihole:/etc/pihole -v ./etc-dnsmasq.d:/etc/dnsmasq.d --cap-add NET_ADMIN --restart unless-stopped pihole/pihole:latest

Note On Capabilities

FTLDNS expects to have the following capabilities available:

  • CAP_NET_BIND_SERVICE: Allows FTLDNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53)
  • CAP_NET_RAW: use raw and packet sockets (needed for handling DHCPv6 requests, and verifying that an IP is not in use before leasing it)
  • CAP_NET_ADMIN: modify routing tables and other network-related operations (in particular inserting an entry in the neighbor table to answer DHCP requests using unicast packets)
  • CAP_SYS_NICE: FTL sets itself as an important process to get some more processing time if the latter is running low
  • CAP_CHOWN: we need to be able to change ownership of log files and databases in case FTL is started as a different user than pihole
  • CAP_SYS_TIME: FTL needs to be able to set the system time to update it using the Network Time Protocol (NTP) in the background

Info

This image automatically grants those capabilities, if available, to the FTLDNS process, even when run as non-root.

By default, docker does not include the NET_ADMIN capability for non-privileged containers, and it is recommended to explicitly add it to the container using --cap-add=NET_ADMIN.

However, if DHCP and IPv6 Router Advertisements are not in use, it should be safe to skip it. For the most paranoid, it should even be possible to explicitly drop the NET_RAW capability to prevent FTLDNS from automatically gaining it.