diff --git a/README.md b/README.md index f732a3e..de51cf0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Docker Pi-hole +[![Build Status](https://github.com/pi-hole/docker-pi-hole/workflows/Test%20&%20Build/badge.svg)](https://github.com/pi-hole/docker-pi-hole/actions?query=workflow%3A%22Test+%26+Build%22) [![Docker Stars](https://img.shields.io/docker/stars/pihole/pihole.svg?maxAge=604800)](https://store.docker.com/community/images/pihole/pihole) [![Docker Pulls](https://img.shields.io/docker/pulls/pihole/pihole.svg?maxAge=604800)](https://store.docker.com/community/images/pihole/pihole) +

Pi-hole

@@ -19,10 +21,11 @@ ## Quick Start -1. Copy docker-compose.yml.example to docker-compose.yml and update as needed. See example below: -[Docker-compose](https://docs.docker.com/compose/install/) example: +Using [Docker-compose](https://docs.docker.com/compose/install/): -```yaml +1. Copy the below docker compose example and update as needed + +```yml version: "3" # More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/ @@ -53,31 +56,11 @@ services: 2. Run `docker compose up -d` to build and start pi-hole (Syntax may be `docker-compose` on older systems) 3. If using Docker's default `bridge` network setting, set the environment variable `FTLCONF_dns_listeningMode` to `all` -[Here is an equivalent docker run script](https://github.com/pi-hole/docker-pi-hole/blob/master/examples/docker_run.sh). +nb. Volumes are recommended for persisting data across container re-creations for updating images. -## Overview +### Automatic Ad List Updates -A [Docker](https://www.docker.com/what-docker) project to make a lightweight x86 and ARM container with [Pi-hole](https://pi-hole.net) functionality. - -1) Install Docker. [Docker-compose](https://docs.docker.com/compose/install/) is also recommended. -2) Use the above quick start example, customize if desired. -3) Enjoy! - -[![Build Status](https://github.com/pi-hole/docker-pi-hole/workflows/Test%20&%20Build/badge.svg)](https://github.com/pi-hole/docker-pi-hole/actions?query=workflow%3A%22Test+%26+Build%22) [![Docker Stars](https://img.shields.io/docker/stars/pihole/pihole.svg?maxAge=604800)](https://store.docker.com/community/images/pihole/pihole) [![Docker Pulls](https://img.shields.io/docker/pulls/pihole/pihole.svg?maxAge=604800)](https://store.docker.com/community/images/pihole/pihole) - -## Running Pi-hole Docker - -This container uses 2 popular ports, port 53 and port 80, so **may conflict with existing applications ports**. If you have no other services or docker containers using port 53/80 (if you do, keep reading below for a reverse proxy example), the minimum arguments required to run this container are in the script [docker_run.sh](https://github.com/pi-hole/docker-pi-hole/blob/master/examples/docker_run.sh) - -If you're using a Red Hat based distribution with an SELinux Enforcing policy add `:z` to line with volumes like so: - -``` - -v "$(pwd)/etc-pihole:/etc/pihole:z" \ -``` - -Volumes are recommended for persisting data across container re-creations for updating images. - -**Automatic Ad List Updates** - `cron` is baked into the container and will grab the newest versions of your lists and flush your logs. This happens once per week in the small hours of Sunday morning. +`cron` is baked into the container and will grab the newest versions of your lists and flush your logs. This happens once per week in the small hours of Sunday morning. ## Running DHCP from Docker Pi-Hole @@ -139,9 +122,8 @@ Here is a rundown of other arguments for your docker-compose / docker run. - Port conflicts? Stop your server's existing DNS / Web services. - Don't forget to stop your services from auto-starting again after you reboot - Ubuntu users see below for more detailed information -- You can map other ports to Pi-hole port 80 using docker's port forwarding like this `-p 8080:80` if you are using the default blocking mode. If you are using the legacy IP blocking mode, you should not remap this port. - - [Here is an example of running with nginxproxy/nginx-proxy](https://github.com/pi-hole/docker-pi-hole/blob/master/examples/docker-compose-nginx-proxy.yml) (an nginx auto-configuring docker reverse proxy for docker) on my port 80 with Pi-hole on another port. Pi-hole needs to be `DEFAULT_HOST` env in nginxproxy/nginx-proxy and you need to set the matching `VIRTUAL_HOST` for the Pi-hole's container. Please read nginxproxy/nginx-proxy readme for more info if you have trouble. - Docker's default network mode `bridge` isolates the container from the host's network. This is a more secure setting, but requires setting the Pi-hole DNS option for _Interface listening behavior_ to "Listen on all interfaces, permit all origins". +- If you're using a Red Hat based distribution with an SELinux Enforcing policy add `:z` to line with volumes ### Installing on Ubuntu or Fedora @@ -235,7 +217,7 @@ We install all pihole utilities so the the built in [pihole commands](https://di ### Customizations -The webserver and DNS service inside the container can be customized if necessary. Any configuration files you volume mount into `/etc/dnsmasq.d/` will be loaded by dnsmasq when the container starts or restarts or if you need to modify the Pi-hole config it is located at `/etc/dnsmasq.d/01-pihole.conf`. The docker start scripts runs a config test prior to starting so it will tell you about any errors in the docker log. +The webserver and DNS service inside the container can be customized if necessary. Any configuration files you volume mount into `/etc/dnsmasq.d/` will be loaded by dnsmasq when the container starts or restarts. ## Note on Capabilities diff --git a/examples/docker-compose-caddy-proxy.yml b/examples/docker-compose-caddy-proxy.yml index 99d54d7..0ee3cc1 100644 --- a/examples/docker-compose-caddy-proxy.yml +++ b/examples/docker-compose-caddy-proxy.yml @@ -22,7 +22,7 @@ services: # More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/ pihole: - depends_on: + depends_on: - caddy container_name: pihole #dns: # Optional. Specify desired upstream DNS servers here. @@ -37,17 +37,15 @@ services: # Following are NOT proxied through Caddy, bound to host net instead: - "53:53/udp" - "53:53/tcp" - - "853:853/tcp" # DNS-over-TLS + - "853:853/tcp" # DNS-over-TLS #- "67:67/udp" # DHCP, if desired. If not bound to host net you need an mDNS proxy service configured somewhere on host net. # ref: https://docs.pi-hole.net/docker/DHCP/ environment: TZ: 'America/New_York' # Supported TZ database names: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#Time_Zone_abbreviations - WEBPASSWORD: 'password' # Only used on first boot, change with pihole cli then comment out here. + FTLCONF_webserver_api_password: 'password' volumes: - './etc-pihole:/etc/pihole' - './etc-dnsmasq.d:/etc/dnsmasq.d' - - './etc-lighttpd/external.conf:/etc/lighttpd/external.conf' # Recommend leave as bind mount for easier editing. - # ref for why you may need to change this file: https://docs.pi-hole.net/guides/webserver/caddy/#modifying-lighttpd-configuration #cap_add: # Uncomment if using Pi-hole as DHCP server # https://github.com/pi-hole/docker-pi-hole#note-on-capabilities #- NET_ADMIN # ONLY required if you are using Pi-hole as your DHCP server, else remove for better security diff --git a/examples/docker-compose-nginx-proxy.yml b/examples/docker-compose-nginx-proxy.yml deleted file mode 100644 index 48b34f9..0000000 --- a/examples/docker-compose-nginx-proxy.yml +++ /dev/null @@ -1,59 +0,0 @@ -version: "3" - -# https://github.com/pi-hole/docker-pi-hole/blob/master/README.md - -services: - nginx-proxy: - image: nginxproxy/nginx-proxy - ports: - - '80:80' - environment: - DEFAULT_HOST: pihole.yourDomain.lan - volumes: - - '/var/run/docker.sock:/tmp/docker.sock' - restart: always - - pihole: - image: pihole/pihole:latest - ports: - - '53:53/tcp' - - '53:53/udp' - - "67:67/udp" - - '8053:80/tcp' - volumes: - - './etc-pihole:/etc/pihole' - - './etc-dnsmasq.d:/etc/dnsmasq.d' - # run `touch ./var-log/pihole.log` first unless you like errors - # - './var-log/pihole.log:/var/log/pihole/pihole.log' - # Recommended but not required (DHCP needs NET_ADMIN) - # https://github.com/pi-hole/docker-pi-hole#note-on-capabilities - cap_add: - - NET_ADMIN - environment: - ServerIP: 192.168.41.55 - PROXY_LOCATION: pihole - VIRTUAL_HOST: pihole.yourDomain.lan - VIRTUAL_PORT: 80 - extra_hosts: - # Resolve to nothing domains (terminate connection) - - 'nw2master.bioware.com nwn2.master.gamespy.com:0.0.0.0' - # LAN hostnames for other docker containers using nginx-proxy - - 'yourDomain.lan:192.168.41.55' - - 'pihole pihole.yourDomain.lan:192.168.41.55' - - 'ghost ghost.yourDomain.lan:192.168.41.55' - - 'wordpress wordpress.yourDomain.lan:192.168.41.55' - restart: always - -# Another container you might want to have running through the proxy -# Note it also have ENV Vars like pihole and a host under pihole's extra_hosts -# ghost: -# image: fractalf/ghost -# ports: -# - '2368:2368/tcp' -# volumes: -# - '/etc/ghost:/ghost-override' -# environment: -# PROXY_LOCATION: ghost -# VIRTUAL_HOST: ghost.yourDomain.lan -# VIRTUAL_PORT: 2368 -# restart: always diff --git a/examples/docker-compose.yml.example b/examples/docker-compose.yml.example deleted file mode 100644 index f52e184..0000000 --- a/examples/docker-compose.yml.example +++ /dev/null @@ -1,25 +0,0 @@ -version: "3" - -# https://github.com/pi-hole/docker-pi-hole/blob/master/README.md - -services: - pihole: - container_name: pihole - image: pihole/pihole:latest - # For DHCP it is recommended to remove these ports and instead add: network_mode: "host" - ports: - - "53:53/tcp" - - "53:53/udp" - - "67:67/udp" - - "80:80/tcp" - environment: - TZ: 'America/Chicago' - # WEBPASSWORD: 'set a secure password here or it will be random' - # Volumes store your data between container upgrades - volumes: - - './etc-pihole:/etc/pihole' - - './etc-dnsmasq.d:/etc/dnsmasq.d' - # https://github.com/pi-hole/docker-pi-hole#note-on-capabilities - cap_add: - - NET_ADMIN - restart: unless-stopped # Recommended but not required (DHCP needs NET_ADMIN) diff --git a/examples/docker-pi-hole.cron b/examples/docker-pi-hole.cron deleted file mode 100644 index 669c96f..0000000 --- a/examples/docker-pi-hole.cron +++ /dev/null @@ -1,31 +0,0 @@ -# Pi-hole: A black hole for Internet advertisements -# (c) 2015, 2016 by Jacob Salmela -# Network-wide ad blocking via your Raspberry Pi -# http://pi-hole.net -# Updates ad sources every week -# -# Pi-hole is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 2 of the License, or -# (at your option) any later version. -# -# This file is under source-control of the Pi-hole installation and update -# scripts, any changes made to this file will be overwritten when the softare -# is updated or re-installed. Please make any changes to the appropriate crontab -# or other cron file snippets. - -# Your container name goes here: -DOCKER_NAME=pihole -PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin - -# Pi-hole: Update the ad sources once a week on Sunday at 01:59 -# Download any updates from the adlists -59 1 * * 7 root PATH="$PATH:/usr/local/bin/" docker exec $DOCKER_NAME pihole updateGravity > /dev/null - -# Update docker-pi-hole by pulling the latest docker image and re-creating your container. -# pihole software update commands are unsupported in docker! -#30 2 * * 7 root PATH="$PATH:/usr/local/bin/" docker exec $DOCKER_NAME pihole updatePihole > /dev/null - -# Pi-hole: Flush the log daily at 00:00 so it doesn't get out of control -# Stats will be viewable in the Web interface thanks to the cron job above -00 00 * * * root PATH="$PATH:/usr/local/bin/" docker exec $DOCKER_NAME pihole flush > /dev/null diff --git a/examples/docker_run.sh b/examples/docker_run.sh deleted file mode 100755 index 68df5db..0000000 --- a/examples/docker_run.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/bin/bash - -# https://github.com/pi-hole/docker-pi-hole/blob/master/README.md - -# You can customize where to store persistent data by setting the `PIHOLE_BASE` environment -# variable when invoking `docker_run.sh` (e.g. `PIHOLE_BASE=/opt/pihole-storage ./docker_run.sh`). -# If `PIHOLE_BASE` is not set, files are stored in your current directory when you invoke the script. -PIHOLE_BASE="${PIHOLE_BASE:-$(pwd)}" -[[ -d "$PIHOLE_BASE" ]] || mkdir -p "$PIHOLE_BASE" || { echo "Couldn't create storage directory: $PIHOLE_BASE"; exit 1; } - -# Note: FTLCONF_LOCAL_IPV4 should be replaced with your external ip. -docker run -d \ - --name pihole \ - -p 53:53/tcp -p 53:53/udp \ - -p 80:80 \ - -e TZ="America/Chicago" \ - -v "${PIHOLE_BASE}/etc-pihole:/etc/pihole" \ - -v "${PIHOLE_BASE}/etc-dnsmasq.d:/etc/dnsmasq.d" \ - --dns=127.0.0.1 --dns=1.1.1.1 \ - --restart=unless-stopped \ - --hostname pi.hole \ - pihole/pihole:latest - -printf 'Starting up pihole container ' -for i in $(seq 1 20); do - if [ "$(docker inspect -f "{{.State.Health.Status}}" pihole)" == "healthy" ] ; then - printf ' OK' - echo -e "\n$(docker logs pihole 2> /dev/null | grep 'password:') for your pi-hole: http://${IP}/admin/" - exit 0 - else - sleep 3 - printf '.' - fi - - if [ $i -eq 20 ] ; then - echo -e "\nTimed out waiting for Pi-hole start, consult your container logs for more info (\`docker logs pihole\`)" - exit 1 - fi -done; diff --git a/examples/pihole.service b/examples/pihole.service deleted file mode 100644 index b4cbad7..0000000 --- a/examples/pihole.service +++ /dev/null @@ -1,13 +0,0 @@ -[Unit] -Description=pihole -Requires=docker.service multi-user.target -After=docker.service network-online.target dhcpd.service - -[Service] -Restart=always -ExecStart=/usr/bin/docker start -a pihole -ExecStop=/usr/bin/docker stop -t 2 pihole - -[Install] -WantedBy=multi-user.target -