a bunch of documentation tweaks
This commit is contained in:
diginc
parent
13b7914812
commit
c3c94b8955
|
|
@ -1 +0,0 @@
|
|||
alpine.docker
|
||||
75
README.md
75
README.md
|
|
@ -1,8 +1,8 @@
|
|||
A [Docker](https://www.docker.com/what-docker) project to make lightweight x86 and ARM container with [pi-hole](https://pi-hole.net) functionality. Why? Maybe you don't have a Raspberry Pi lying around but you do have a Docker server.
|
||||
A [Docker](https://www.docker.com/what-docker) project to make lightweight x86 and ARM container with [pi-hole](https://pi-hole.net) functionality. Why? Originally designed to be a quick, easy, and portable way to run x86 Pi-Hole, it now has an arm specific tag too.
|
||||
|
||||
**Now with ARM (actual docker-pi) support!** Just install docker on your Rasberry-Pi and run docker image `diginc/pi-hole:arm` tag (see below for full required command).
|
||||
|
||||
* The current Raspbian install is simply `curl -sSL https://get.docker.com | sh` [[1]](https://www.raspberrypi.org/blog/docker-comes-to-raspberry-pi/)
|
||||
1) Install docker for your [ARM64/x86 system](https://www.docker.com/community-edition) or [ARMv6l/ARMv7 system](https://www.raspberrypi.org/blog/docker-comes-to-raspberry-pi/) using those links.
|
||||
2) Use the appropriate tag (x86 can use default tag, ARM users need to use the `arm` tag) in the below `docker run` command
|
||||
3) Enjoy!
|
||||
|
||||
[](https://travis-ci.org/diginc/docker-pi-hole) [](https://store.docker.com/community/images/diginc/pi-hole) [](https://store.docker.com/community/images/diginc/pi-hole)
|
||||
|
||||
|
|
@ -10,12 +10,11 @@ A [Docker](https://www.docker.com/what-docker) project to make lightweight x86 a
|
|||
|
||||
## Running Pi-Hole Docker
|
||||
|
||||
[DockerCloud](https://store.docker.com/community/images/diginc/pi-hole) automatically builds the latest docker-pi-hole changes into images which can easily be pulled and ran with a simple `docker run` command.
|
||||
[DockerCloud](https://store.docker.com/community/images/diginc/pi-hole) automatically builds the latest docker-pi-hole changes into images which can easily be pulled and ran with a simple `docker run` command. Changes and updates under development or testing can be found on the [dev tags](#development)
|
||||
|
||||
One crucial thing to know before starting is the docker-pi-hole container needs port 53 and port 80, 2 very popular ports that may conflict with existing applications. If you have no other services or dockers using port 53/80 (if you do, keep reading below for a reverse proxy example), the minimum options required to run this container are in the script [docker_run.sh](https://github.com/diginc/docker-pi-hole/blob/master/docker_run.sh) or summarized here:
|
||||
One crucial thing to know before starting is this container needs port 53 and port 80, 2 very popular ports that may conflict with existing applications. If you have no other services or dockers 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/diginc/docker-pi-hole/blob/master/docker_run.sh) or summarized here:
|
||||
|
||||
```
|
||||
IMAGE='diginc/pi-hole'
|
||||
IP_LOOKUP="$(ip route get 8.8.8.8 | awk '{ print $NF; exit }')" # May not work for VPN / tun0
|
||||
IPv6_LOOKUP="$(ip -6 route get 2001:4860:4860::8888 | awk '{ print $10; exit }')" # May not work for VPN / tun0
|
||||
IP="${IP:-$IP_LOOKUP}" # use $IP, if set, otherwise IP_LOOKUP
|
||||
|
|
@ -24,12 +23,12 @@ IPv6="${IPv6:-$IPv6_LOOKUP}" # use $IPv6, if set, otherwise IP_LOOKUP
|
|||
docker run -d \
|
||||
--name pihole \
|
||||
-p 53:53/tcp -p 53:53/udp -p 80:80 \
|
||||
-v </path/to/store/pihole>:/etc/pihole \
|
||||
-v </path/to/store/dnsmasq.d>:/etc/dnsmasq.d \
|
||||
-v "$(pwd)/pihole/:/etc/pihole/" \
|
||||
-v "$(pwd)/dnsmasq.d/:/etc/dnsmasq.d/" \
|
||||
-e ServerIP="${IP:-$(ip route get 8.8.8.8 | awk '{ print $NF; exit }')}" \
|
||||
-e ServerIPv6="${IPv6:-$(ip -6 route get 2001:4860:4860::8888 | awk '{ print $10; exit }')}" \
|
||||
--restart=always \
|
||||
diginc/pi-hole
|
||||
diginc/pi-hole:alpine
|
||||
```
|
||||
|
||||
Volumes aren't required but are recommended for persisting data across docker re-creations for updating images. This is just an example and might need changing. As mentioned on line 2, the auto IP_LOOKUP variable may not work for VPN tunnel interfaces.
|
||||
|
|
@ -38,25 +37,33 @@ Volumes aren't required but are recommended for persisting data across docker re
|
|||
|
||||
## Environment Variables
|
||||
|
||||
In addition to the required environment variable you saw above (`-e ServerIP="$IP"`) there are optional ones if you want to customize various things inside the docker container:
|
||||
There are other environment variables if you want to customize various things inside the docker container:
|
||||
|
||||
| Env Variable | Default | Description |
|
||||
| ------------ | ------- | ----------- |
|
||||
| ServerIP | REQUIRED! | Set to your server's external IP in order to override what Pi-Hole users requests get sent to. This container is designed to fail when not set since it is pretty useless without it. |
|
||||
| ServerIPv6 | optional | Where IPv6 ad requests end up, not required if you're not running ipv6 network |
|
||||
| WEBPASSWORD | <random> | Recommended! Set this to your desired password or on first boot we'll randomly set one. `docker logs pihole` can tell you what it got set to. To change it check out the tips below |
|
||||
| DNS1 | 8.8.8.8 | Primary upstream DNS for Pi-Hole's DNSMasq to use, defaults to google |
|
||||
| DNS2 | 8.8.4.4 | Secondary upstream DNS for Pi-Hole's DNSMasq to use, defaults to google |
|
||||
| VIRTUAL_HOST | Server_IP | What your web server 'virtual host' is, accessing admin through this Hostname/IP allows you to make changes to the whitelist / blacklists in addition to the default 'http://pi.hole/admin/' address |
|
||||
| IPv6 | True | Allows forced disabling of IPv6 for docker setups that can't support it (like unraid) |
|
||||
| TZ | UCT | Customize your container's timezone, useful if you use the cron for pihole updates |
|
||||
| Docker Environment Var. | Description |
|
||||
| ----------------------- | ----------- |
|
||||
| `-e ServerIP=<Host's IP>`<br/> **Required** | Set to your server's external IP to block ads fully
|
||||
| `-e ServerIPv6=<Host's IPv6>`<br/> *Required if using IPv6* | **If you have a v6 network** set to your server's external IPv6 to block IPv6 ads fully
|
||||
| `-e TZ=<Timezone>`<br/> **Recommended** *Default: UTC* | Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to make sure logs rotate ad midnight instead of your offset for London
|
||||
| `-e WEBPASSWORD=<Admin password>`<br/> **Recommended** *Default: random* | http://pi.hole/admin password. Run `docker logs pihole | grep random` to find your random pass.
|
||||
| `-e DNS1=<IP>`<br/> *Optional* *Default: 8.8.8.8* | Primary upstream DNS provider, default is google DNS
|
||||
| `-e DNS2=<IP>`<br/> *Optional* *Default: 8.8.4.4* | Secondary upstream DNS provider, default is google DNS
|
||||
| `-e VIRTUAL_HOST=<Custom Hostname>`<br/> *Optional* *Default: $ServerIP* | What your web server 'virtual host' is, accessing admin through this Hostname/IP allows you to make changes to the whitelist / blacklists in addition to the default 'http://pi.hole/admin/' address
|
||||
| `-e IPv6=<True\|False>`<br/> *Optional* *Default: True* | For unraid compatibility, strips out all the IPv6 configuration from DNS/Web services when false.
|
||||
| `-e INTERFACE=<NIC>`<br/> *Advanced/Optional* | The default works fine with our basic example docker run commands. If you're trying to use DHCP with `--net host` mode then you may have to customize this or DNSMASQ_LISTENING.
|
||||
| `-e DNSMASQ_LISTENING=<local\|all\|NIC>`<br/> *Advanced/Optional* | `local` listens on all local subnets, `all` permits listening on internet origin subnets in addition to local.
|
||||
|
||||
*OPTIONAL Advanced* Environment Variables
|
||||
Here is a rundown of the other arguments passed into the recommended
|
||||
|
||||
| Env Variable | Default | Description |
|
||||
| ------------ | ------- | ----------- |
|
||||
| INTERFACE | eth0 | The default works fine with our basic example docker run commands. If you're trying to use DHCP with `--net host` mode then you may have to customize this or DNSMASQ_LISTENING.
|
||||
| DNSMASQ_LISTENING | | If set to `local` or `all` this will override `INTERFACE`. `local` listens on all local subnets, `all` permits listening on internet origin subnets in addition to local.
|
||||
| Docker Arguments | Description |
|
||||
| ---------------- | ----------- |
|
||||
| `-p 80:80`<br/>`-p 53:53/tcp -p 53:53/tcp`<br/> **Recommended** | Ports to expose, the bare minimum ports required for pi-holes HTTP and DNS services
|
||||
| `--restart=always`<br/> **Recommended** | Automatically (re)start your pihole on boot or in the event of a crash
|
||||
| `-v /dir/for/pihole:/etc/pihole`<br/> **Recommended** | Volumes for your pihole configs help persist changes across docker image updates
|
||||
| `-v /dir/for/dnsmasq.d:/etc/dnsmasq.d`<br/> **Recommended** | Volumes for your dnsmasq configs help persist changes across docker image updates
|
||||
| `--net=host`<br/> *Optional* | Alternative to `-p <port>:<port>` arguments (Cannot be used at same time as -p) if you don't run any other web application
|
||||
| `--cap-add=NET_ADMIN`<br/> *Optional* | If you want to attempt DHCP (not fully tested or supported) I'd suggest this with --net=host
|
||||
|
||||
If you're a fan of [docker-compose](https://docs.docker.com/compose/install/) I have [example docker-compose.yml files](https://github.com/diginc/docker-pi-hole/blob/master/doco-example.yml) in github which I think are a nicer way to represent such long run commands.
|
||||
|
||||
## Tips and Tricks
|
||||
|
||||
|
|
@ -70,15 +77,6 @@ In addition to the required environment variable you saw above (`-e ServerIP="$I
|
|||
* You can still map other ports to pi-hole port 80 using docker's port forwarding like this `-p 8080:80`, but again the ads won't render propertly. Changing the inner port 80 shouldn't be required unless you run docker host networking mode.
|
||||
* [Here is an example of running with jwilder/proxy](https://github.com/diginc/docker-pi-hole/blob/master/jwilder-proxy-example-doco.yml) (an nginx auto-configuring docker reverse proxy for docker) on my port 80 with pihole on another port. Pi-hole needs to be `DEFAULT_HOST` env in jwilder/proxy and you need to set the matching `VIRTUAL_HOST` for the pihole's container. Please read jwilder/proxy readme for more info if you have trouble. I tested this basic example which is based off what I run.
|
||||
|
||||
## Volume Mounts
|
||||
Here are some useful volume mount options to persist your history of stats in the admin interface, or add custom whitelists/blacklists. **Create these files on the docker host first or you'll get errors**:
|
||||
|
||||
* `docker run -v /var/log/pihole.log:/var/log/pihole.log ...` (plus all of the minimum options added)
|
||||
* `touch /var/log/pihole.log` on your docker server first or you will end up with a directory there (silly docker!)
|
||||
* `docker run -v /etc/pihole/:/etc/pihole/ ...` (plus all of the minimum options added)
|
||||
|
||||
All of these options get really long when strung together in one command, which is why I'm not showing all the full `docker run` commands variations here. This is where [docker-compose](https://docs.docker.com/compose/install/) yml files come in handy for representing [really long docker commands in a readable file format](https://github.com/diginc/docker-pi-hole/blob/master/doco-example.yml).
|
||||
|
||||
## Docker tags and versioning
|
||||
|
||||
The primary docker tags / versions are explained in the following table. [Click here to see the full list of tags](https://store.docker.com/community/images/diginc/pi-hole/tags), I also try to tag with the specific version of Pi-Hole Core for version pinning purposes, the web version that comes with the core releases should be in the [GitHub Release notes](https://github.com/diginc/docker-pi-hole/releases).
|
||||
|
|
@ -119,9 +117,6 @@ The standard pi-hole customization abilities apply to this docker, but with dock
|
|||
|
||||
Why is this style of upgrading good? A couple reasons: Everyone is starting from the same base image which has been tested to know it works. No worrying about upgrading from A to B, B to C, or A to C is required when rolling out updates, it reducing complexity, and simply allows a 'fresh start' every time while preserving customizations with volumes. Basically I'm encouraging [phoenix servers](https://www.google.com/?q=phoenix+servers) principles for your containers.
|
||||
|
||||
### Persisting pihole volume
|
||||
|
||||
`-v my-pihole-configs/:/etc/pihole/` Volume mapping the entire /etc/pihole directory is the easiest way to save all your customizations. Clear out the directory if you want to start from scratch.
|
||||
|
||||
### Pihole features
|
||||
|
||||
|
|
@ -139,9 +134,9 @@ The webserver and DNS service inside the container can be customized if necessar
|
|||
|
||||
Similarly for the webserver you can customize configs in /etc/nginx (*:alpine* tag) and /etc/lighttpd (*:debian* tag).
|
||||
|
||||
## Development [](https://travis-ci.org/diginc/docker-pi-hole)
|
||||
## Development
|
||||
|
||||
If you plan on making a contribution please pull request to the dev branch. I also build tags of the dev branch for bug fix testing after merges have been made:
|
||||
](https://travis-ci.org/diginc/docker-pi-hole) If you plan on making a contribution please pull request to the dev branch. I also build tags of the dev branch for bug fix testing after merges have been made:
|
||||
|
||||
| tag | architecture | description | Dockerfile |
|
||||
| --- | ------------ | ----------- | ---------- |
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
#!/bin/bash
|
||||
IMAGE=${1:-'diginc/pi-hole:alpine'}
|
||||
IP_LOOKUP="$(ip route get 8.8.8.8 | awk '{ print $NF; exit }')" # May not work for VPN / tun0
|
||||
IPv6_LOOKUP="$(ip -6 route get 2001:4860:4860::8888 | awk '{ print $10; exit }')" # May not work for VPN / tun0
|
||||
IP="${IP:-$IP_LOOKUP}" # use $IP, if set, otherwise IP_LOOKUP
|
||||
|
|
@ -11,11 +10,11 @@ echo "IP: ${IP} - IPv6: ${IPv6}"
|
|||
docker run -d \
|
||||
--name pihole \
|
||||
-p 53:53/tcp -p 53:53/udp -p 80:80 \
|
||||
-v /etc/volumes/pihole:/etc/pihole \
|
||||
-v /etc/volumes/dnsmasq.d:/etc/dnsmasq.d \
|
||||
-v "$(pwd)/pihole/:/etc/pihole/" \
|
||||
-v "$(pwd)/dnsmasq.d/:/etc/dnsmasq.d/" \
|
||||
-e ServerIP="${IP:-$(ip route get 8.8.8.8 | awk '{ print $NF; exit }')}" \
|
||||
-e ServerIPv6="${IPv6:-$(ip -6 route get 2001:4860:4860::8888 | awk '{ print $10; exit }')}" \
|
||||
--restart=always \
|
||||
diginc/pi-hole
|
||||
diginc/pi-hole:alpine
|
||||
|
||||
docker logs pihole 2> /dev/null | grep 'password:'
|
||||
|
|
|
|||
|
|
@ -3,12 +3,15 @@ services:
|
|||
pihole:
|
||||
image: diginc/pi-hole:alpine
|
||||
environment:
|
||||
# Your docker host IP is required if you run RUN (not build)
|
||||
ServerIP: 192.168.1.55
|
||||
# enter your docker host IP here
|
||||
ServerIP:
|
||||
# IPv6 Address if your network supports it
|
||||
#ServerIPv6: 192.168.1.55
|
||||
volumes:
|
||||
- "./pihole/:/etc/pihole/"
|
||||
- "./dnsmasq.d/:/etc/dnsmasq.d/"
|
||||
ports:
|
||||
- "53:53/tcp"
|
||||
- "53:53/udp"
|
||||
- "80:80/tcp"
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
restart: always
|
||||
|
|
|
|||
|
|
@ -1,13 +0,0 @@
|
|||
debian:
|
||||
build: .
|
||||
dockerfile: debian.docker
|
||||
environment:
|
||||
# Your docker host IP is required if you run RUN (not build)
|
||||
ServerIP: 192.168.1.55
|
||||
ports:
|
||||
- "53:53/tcp"
|
||||
- "53:53/udp"
|
||||
- "80:80/tcp"
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
restart: always
|
||||
|
|
@ -1,26 +1,28 @@
|
|||
pihole:
|
||||
image: diginc/pi-hole
|
||||
ports:
|
||||
- "53:53/tcp"
|
||||
- "53:53/udp"
|
||||
- "80:80/tcp"
|
||||
cap_add:
|
||||
- NET_ADMIN
|
||||
environment:
|
||||
# enter your docker host IP here
|
||||
ServerIP:
|
||||
# jwilder/proxy envs, see readme for more info
|
||||
PROXY_LOCATION: pihole
|
||||
VIRTUAL_HOST: pihole.yourdomain.local
|
||||
VIRTUAL_PORT: 80
|
||||
# Add your own custom hostnames you need for your domain
|
||||
extra_hosts:
|
||||
# Point any of the jwilder virtual_host addresses
|
||||
# to your docker host ip address
|
||||
- 'pihole.yourdomain.local:192.168.1.55'
|
||||
volumes:
|
||||
# - '/etc/pihole/:/etc/pihole/'
|
||||
# WARNING: if this log don't exist as a file on the host already
|
||||
# docker will try to create a directory in it's place making for lots of errors
|
||||
# - '/var/log/pihole.log:/var/log/pihole.log'
|
||||
restart: always
|
||||
version: "3"
|
||||
services:
|
||||
pihole:
|
||||
image: diginc/pi-hole:alpine
|
||||
ports:
|
||||
- "53:53/tcp"
|
||||
- "53:53/udp"
|
||||
- "80:80/tcp"
|
||||
environment:
|
||||
# enter your docker host IP here
|
||||
ServerIP:
|
||||
# IPv6 Address if your network supports it
|
||||
#ServerIPv6: 192.168.1.55
|
||||
# jwilder/proxy envs, see readme for more info
|
||||
PROXY_LOCATION: pihole
|
||||
VIRTUAL_HOST: pihole.yourdomain.local
|
||||
VIRTUAL_PORT: 80
|
||||
# Add your own custom hostnames you need for your domain
|
||||
extra_hosts:
|
||||
# Point any of the jwilder virtual_host addresses
|
||||
# to your docker host ip address
|
||||
- 'pihole.yourdomain.local:192.168.1.55'
|
||||
volumes:
|
||||
# - '/etc/pihole/:/etc/pihole/'
|
||||
# WARNING: if this log don't exist as a file on the host already
|
||||
# docker will try to create a directory in it's place making for lots of errors
|
||||
# - '/var/log/pihole.log:/var/log/pihole.log'
|
||||
restart: always
|
||||
|
|
|
|||
Loading…
Reference in New Issue