Update README.md
This commit is contained in:
Adam Hill
GitHub
parent
c290324185
commit
2d1c515d25
40
README.md
40
README.md
|
|
@ -12,18 +12,14 @@
|
|||
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 for your [x86-64 system](https://www.docker.com/community-edition) or [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 images from [pihole/pihole:v4.0_armhf](https://store.docker.com/community/images/pihole/pihole/tags)) in the below `docker run` command
|
||||
2) Use the below `docker run` command, customize if desired.
|
||||
3) Enjoy!
|
||||
|
||||
[](https://travis-ci.org/pi-hole/docker-pi-hole) [](https://store.docker.com/community/images/pihole/pihole) [](https://store.docker.com/community/images/pihole/pihole)
|
||||
|
||||
[](https://gitter.im/pihole/docker-pi-hole?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
|
||||
## Running Pi-hole Docker
|
||||
|
||||
[DockerCloud](https://store.docker.com/community/images/pihole/pihole) 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 in the [dev tags](#development) section.
|
||||
|
||||
One crucial thing to know before starting is this container needs port 53 and port 80, two very popular ports that may conflict with existing applications. 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/docker_run.sh) or summarized here:
|
||||
This container uses 2 peopular 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/docker_run.sh) or summarized here:
|
||||
|
||||
```bash
|
||||
IP_LOOKUP="$(ip route get 8.8.8.8 | awk '{ print $NF; exit }')" # May not work for VPN / tun0
|
||||
|
|
@ -52,7 +48,7 @@ echo -n "Your password for https://${IP}/admin/ is "
|
|||
docker logs pihole 2> /dev/null | grep 'password'
|
||||
```
|
||||
|
||||
**This is just an example and might need changing.** Volumes are stored in the directory `$DOCKER_CONFIGS` and are recommended for persisting data across docker re-creations for updating images. As mentioned on line 2, the auto `IP_LOOKUP` variable may not work for VPN tunnel interfaces.
|
||||
**This is just an example and might need changing.** Volumes are stored in the directory `$DOCKER_CONFIGS` and are recommended for persisting data across docker re-creations for updating images. The IP lookup variables may not work for everyone, please review their values and hard code IP and IPv6 if necessary.
|
||||
|
||||
Two recently added ports to the `docker run` and `docker-compose` examples are port 67 and 443. Port 67 is for users who wish to have Pi-hole run a DHCP server. Port 443 is to provide a sinkhole for ads that use SSL. If only port 80 is used, then blocked HTTPS queries will fail to connect to port 443 and may cause long loading times. Rejecting 443 on your firewall can also serve this same purpose. Ubuntu firewall example: `sudo ufw reject https`
|
||||
|
||||
|
|
@ -107,33 +103,28 @@ If you're a fan of [docker-compose](https://docs.docker.com/compose/install/) I
|
|||
|
||||
## Docker tags and versioning
|
||||
|
||||
The primary docker tags / versions are explained in the following table. [Click here to see the full list of x86 tags](https://store.docker.com/community/images/pihole/pihole/tags) ([arm tags are here](https://store.docker.com/community/images/pihole/pihole/tags)), I also try to tag with the specific version of Pi-hole Core for version archival purposes, the web version that comes with the core releases should be in the [GitHub Release notes](https://github.com/pi-hole/docker-pi-hole/releases).
|
||||
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/pihole/pihole/tags) ([arm tags are here](https://store.docker.com/community/images/pihole/pihole/tags)), I also try to tag with the specific version of Pi-hole Core for version archival purposes, the web version that comes with the core releases should be in the [GitHub Release notes](https://github.com/pi-hole/docker-pi-hole/releases).
|
||||
|
||||
| tag | architecture | description | Dockerfile |
|
||||
| --- | ------------ | ----------- | ---------- |
|
||||
| `latest` / `v4.0` | x86 | Debian x86 image, container running lighttpd and dnsmasq | [Dockerfile](https://github.com/pi-hole/docker-pi-hole/blob/master/Dockerfile_amd64) |
|
||||
|
||||
| `latest` | auto detect | x86, arm, or arm64 container, docker auto detects your architecture. | [Dockerfile](https://github.com/pi-hole/docker-pi-hole/blob/master/Dockerfile_amd64) |
|
||||
| `v4.0.0-1` | auto detect | Versioned tags, if you want to pin against a specific version, use one of thesse | |
|
||||
| `v4.0.0-1_<arch>` | based on tag | Specific architectures tags | |
|
||||
| `development` | auto detect | like latest tag, but for the development branch (pushed occasionally) | |
|
||||
|
||||
### `pihole/pihole:latest` [](https://microbadger.com/images/pihole/pihole "Get your own image badge on microbadger.com") [](https://microbadger.com/images/pihole/pihole "Get your own version badge on microbadger.com") [](https://microbadger.com/images/pihole/pihole "Get your own version badge on microbadger.com")
|
||||
|
||||
This version of the docker aims to be as close to a standard Pi-hole installation by using the recommended base OS and the exact configs and scripts (minimally modified to get them working). This enables fast updating when an update comes from Pi-hole.
|
||||
|
||||
### `pihole/pihole:v4.0_armhf` [](https://microbadger.com/images/pihole/pihole "Get your own image badge on microbadger.com")
|
||||
Latest version of ARMv7-compatible pihole image
|
||||
|
||||
https://hub.docker.com/r/pihole/pihole/tags/
|
||||
|
||||
### `pihole/pihole:v4.0_aarch64` [](https://microbadger.com/images/pihole/pihole "Get your own image badge on microbadger.com")
|
||||
Latest version of ARM64-compatible pihole image
|
||||
|
||||
https://hub.docker.com/r/pihole/pihole/tags/
|
||||
|
||||
## Upgrading, Persistence, and Customizations
|
||||
|
||||
The standard Pi-hole customization abilities apply to this docker, but with docker twists such as using docker volume mounts to map host stored file configurations over the container defaults. Volumes are also important to persist the configuration in case you have removed the Pi-hole container which is a typical docker upgrade pattern.
|
||||
|
||||
### Upgrading
|
||||
### Upgrading / Reconfiguring
|
||||
|
||||
`pihole -up` is disabled. Upgrade the docker way instead, please. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often! Just to prove you can.
|
||||
Do not attempt to upgrade (`pihole -up`) or reconfigure (`pihole -r`). New images will be released for upgrades, upgrading by replacing your old container with a fresh upgraded image is the 'docker way'. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often! Just to prove you can.
|
||||
|
||||
1. Download the latest version of the image: `docker pull pihole/pihole`
|
||||
2. Throw away your container: `docker rm -f pihole`
|
||||
|
|
@ -141,8 +132,9 @@ The standard Pi-hole customization abilities apply to this docker, but with dock
|
|||
* If you care about your data (logs/customizations), make sure you have it volume-mapped or it will be deleted in this step.
|
||||
3. Start your container with the newer base image: `docker run <args> pihole/pihole` (`<args>` being your preferred run volumes and env vars)
|
||||
|
||||
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.
|
||||
Why is this style of upgrading good? A couple reasons: Everyone is starting from the same base image which has been tested to known 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 server](https://www.google.com/?q=phoenix+servers) principles for your containers.
|
||||
|
||||
To reconfigure Pi-hole you'll either need to use an existing container environment variables or if there is no a variable for what you need, use the web UI or CLI commands.
|
||||
|
||||
### Pi-hole features
|
||||
|
||||
|
|
@ -166,10 +158,6 @@ As long as your docker system service auto starts on boot and you run your conta
|
|||
|
||||
NOTE: After initial run you may need to manually stop the docker container with "docker stop pihole" before the systemctl can start controlling the container.
|
||||
|
||||
## Development
|
||||
|
||||
Development image tags coming soon
|
||||
|
||||
# User Feedback
|
||||
|
||||
Please report issues on the [GitHub project](https://github.com/pi-hole/docker-pi-hole) when you suspect something docker related. Pi-hole questions are best answered on our [user forums](https://github.com/pi-hole/pi-hole/blob/master/README.md#get-help-or-connect-with-us-on-the-web). Ping me (@diginc) on the forums if it's a docker container and you're not sure if it's docker related.
|
||||
Please report issues on the [GitHub project](https://github.com/pi-hole/docker-pi-hole) when you suspect something docker related. Pi-hole or general docker questions are best answered on our [user forums](https://github.com/pi-hole/pi-hole/blob/master/README.md#get-help-or-connect-with-us-on-the-web). Ping me (@diginc) on the forums if it's a docker container and you're not sure if it's docker related.
|
||||
|
|
|
|||
Loading…
Reference in New Issue