Skip to content

Commit 751b9c2

Browse files
PromoFauxPromoFaux
committed
move info from docker readme to the docs
Signed-off-by: Adam Warner <[email protected]>
1 parent 6451016 commit 751b9c2

File tree

3 files changed

+163
-123
lines changed

3 files changed

+163
-123
lines changed

‎docs/docker/configuration.md‎

Lines changed: 122 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
1+
<!-- markdownlint-disable MD051 MD046 -->
12
# Configuration
23

3-
The recommended way to configure the Pi-hole docker container is by utilizing [environment variables](https://docs.docker.com/compose/how-tos/environment-variables/), however if you are persisting your `/etc/pihole` directory, you choose instead to set them via the web interface, or by directly editing `pihole.toml`
4+
The recommended way to configure the Pi-hole docker container is by utilizing [environment variables](https://docs.docker.com/compose/how-tos/environment-variables/) for a simple and easily reproducible setup.
5+
6+
If you are persisting your `/etc/pihole` directory, you choose instead to set them via the web interface, or by directly editing `pihole.toml`
47

58
## Environment Variables
69

@@ -27,161 +30,169 @@ An example of how some of these variables may look in your compose file
2730
```yaml
2831
environment:
2932
TZ: europe/London
30-
FTLCONF_dns_revServers: 'true,192.168.0.0/16,192.168.0.1,lan'
31-
FTLCONF_dns_upstreams: '8.8.8.8;8.8.4.4'
33+
FTLCONF_dns_revServers: 'true,192.168.0.0/16,192.168.0.1,lan'
3234
FTLCONF_webserver_api_password: 'correct horse battery staple'
3335
FTLCONF_webserver_port: '8082,443s'
3436
FTLCONF_debug_api: 'true'
37+
38+
# Array Types can either be delimited by semicolon
39+
# If you have only a few items this may be more convienient
40+
FTLCONF_dns_upstreams: '8.8.8.8;8.8.4.4;1.1.1.1;9.9.9.9'
41+
FTLCONF_misc_dnsmasq_lines: 'address=/example.com/192.168.1.1;address=/example.org/192.168.1.2;address=/example.net/192.168.1.3'
42+
43+
# Or YAML Multiline block style can be used for better redability.
44+
# https://yaml.org/spec/1.2.2/#literal-style
45+
FTLCONF_dns_upstreams: |-
46+
8.8.8.8
47+
8.8.4.4
48+
1.1.1.1
49+
9.9.9.9
50+
FTLCONF_misc_dnsmasq_lines: |-
51+
address=/example.com/192.168.1.1
52+
address=/example.org/192.168.1.2
53+
address=/example.net/192.168.1.3
3554
```
3655
37-
### Recommended Variables
56+
### Recommended Environment Variables
3857
39-
#### `TZ` (Default: `UTC`)
58+
| Variable | Description |
59+
| :--- | :--- |
60+
| `TZ` | Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to make sure logs rotate at local midnight instead of at UTC midnight. |
61+
| `FTLCONF_webserver_api_password` | To set a specific password for the web interface (per the quick-start example).<br><br>If this variable is not detected, and you have not already set one previously inside the container via `pihole setpassword` or `pihole-FTL --config webserver.api.password`, then a random password will be assigned on startup, and will be printed to the log.<br><br>You can find this password by running `docker logs pihole` and looking for "random password". See [Setting the Web Interface Password](#setting-the-web-interface-password) below for usage examples. |
62+
| `FTLCONF_dns_upstreams` | Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon<br><br>Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`<br><br>Supports [Docker service names and links](https://docs.docker.com/compose/networking/) instead of IPs e.g `upstream0;upstream1` where upstream0 and upstream1 are the service names of or links to docker services |
4063

41-
Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to make sure logs rotate at local midnight instead of at UTC midnight.
4264

43-
#### `FTLCONF_webserver_api_password` (Default: `unset`)
65+
## Setting the Web Interface Password {: #setting-the-web-interface-password }
4466

45-
To set a specific password for the web interface, use the environment variable `FTLCONF_webserver_api_password` (per the quick-start example). If this variable is not detected, and you have not already set one previously inside the container via `pihole setpassword` or `pihole-FTL --config webserver.api.password`, then a random password will be assigned on startup, and will be printed to the log. You can find this password with the command `docker logs pihole | grep random password` on your host to find this password. See [Notes On Web Interface Password](#notes-on-web-interface-password) below for usage examples.
67+
The web interface password can be set using the `FTLCONF_webserver_api_password` environment variable as documented above or using the `WEBPASSWORD_FILE` environment variable using [Docker Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) or [Docker Swarm secrets](https://docs.docker.com/engine/swarm/secrets/).
4668

4769
!!! note
4870
To _explicitly_ set no password, set `FTLCONF_webserver_api_password: ''`<br/><br/>
4971
Using `pihole setpassword` for the purpose of setting an empty password will not persist between container restarts
5072

51-
#### `FTLCONF_dns_upstreams` (Default: `8.8.8.8;8.8.4.4`)
52-
53-
- Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon
54-
- Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`
55-
- Supports Docker service names and links instead of IPs e.g `upstream0;upstream1` where upstream0 and upstream1 are the service names of or links to docker services
56-
57-
### Other Variables
58-
59-
#### `TAIL_FTL_LOG` (Default: `1`)
60-
61-
Whether or not to output the FTL log when running the container. Can be disabled by setting the value to 0
62-
63-
#### `PIHOLE_UID` (Default: `1000`)
64-
65-
Overrides image's default pihole user id to match a host user id
66-
67-
#### `PIHOLE_GID` (Default: `1000`)
68-
69-
Overrides image's default pihole group id to match a host group id
70-
71-
!!! Warning
72-
For the above two settings, the `id` must not already be in use inside the container!
73+
### Examples
7374

74-
#### `FTL_CMD` (Default: `no-daemon`)
75+
The `FTLCONF_webserver_api_password` variable can be set directly or sourced from files, environment variables, or Docker secrets. Choose the workflow that best matches your deployment.
7576

76-
Customize the options with which dnsmasq gets started. e.g. `no-daemon -- --dns-forward-max 300` to increase max. number of concurrent dns queries on high load setups.
77+
=== "Docker Compose"
78+
Provide the password directly inside your Compose file.
7779

78-
#### `DNSMASQ_USER` (Default: `pihole`)
79-
80-
Allows changing the user that FTLDNS runs as. Default: pihole, some systems such as Synology NAS may require you to change this to root (See [pihole/docker-pi-hole#963](https://github.com/pi-hole/docker-pi-hole/issues/963))
81-
82-
#### `ADDITIONAL_PACKAGES` (Default: unset)
83-
84-
Mostly for development purposes, this just makes it easier for those of us that always like to have whatever additional tools we need inside the container for debugging.
85-
86-
Adding packages here is the same as running `apk add <package>` inside the container
87-
88-
#### `PH_VERBOSE` (Default: `0`)
89-
90-
Setting this environment variable to `1` will set `-x`, making the scripts that run on container startup more verbose. Useful for debugging only.
80+
```yaml
81+
...
82+
environment:
83+
FTLCONF_webserver_api_password: 'correct horse battery staple'
84+
...
85+
```
9186

92-
#### `WEBPASSWORD_FILE` (Default: unset)
87+
=== "Docker Compose (env var)"
88+
Reference an [environment variable](https://docs.docker.com/compose/how-tos/environment-variables/) such as `ADMIN_PASSWORD`.
9389

94-
Set the web interface password using [Docker Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) if using Compose or [Docker Swarm secrets](https://docs.docker.com/engine/swarm/secrets/) if using Docker Swarm. If `FTLCONF_webserver_api_password` is set, `WEBPASSWORD_FILE` is ignored. If `FTLCONF_webserver_api_password` is empty, and `WEBPASSWORD_FILE` is set to a valid readable file path, then `FTLCONF_webserver_api_password` will be set to the contents of `WEBPASSWORD_FILE`. See [Notes On Web Interface Password](#notes-on-web-interface-password) below for usage examples.
90+
```yaml
91+
...
92+
environment:
93+
FTLCONF_webserver_api_password: ${ADMIN_PASSWORD}
94+
...
95+
```
9596

96-
### Variable Formatting
97+
Define it in the shell:
9798

98-
Environment variables may be set in the format given here, or they may be entirely uppercase in the conventional manner.
99+
```bash
100+
export ADMIN_PASSWORD=correct horse battery staple
101+
docker compose -f compose.yaml
102+
```
99103

100-
For example, both `FTLCONF_dns_upstreams` and `FTLCONF_DNS_UPSTREAMS` are functionally equivalent when used as environment variables.
104+
Or in an `.env` file kept alongside your Compose yaml:
101105

102-
## Notes On Web Interface Password
106+
```bash
107+
$ cat .env
108+
ADMIN_PASSWORD=correct horse battery staple
109+
$ docker compose -f compose.yaml
110+
```
103111

104-
The web interface password can be set using the `FTLCONF_webserver_api_password` environment variable as documented above or using the `WEBPASSWORD_FILE` environment variable using [Docker Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) or [Docker Swarm secrets](https://docs.docker.com/engine/swarm/secrets/).
112+
=== "Docker Compose secret"
113+
Use `WEBPASSWORD_FILE` with Docker secrets to avoid storing the password directly in your Compose file.
105114

106-
### `FTLCONF_webserver_api_password` Examples
115+
```bash
116+
$ cat pihole_password.txt
117+
correct horse battery staple
118+
```
107119

108-
The `FTLCONF_webserver_api_password` variable can be set in a `docker run` command or as an environment attribute in a Docker Compose yaml file.
120+
```yaml
121+
---
122+
services:
123+
pihole:
124+
container_name: pihole
125+
image: pihole/pihole:latest
109126
110-
#### Docker run example
127+
# lines deleted
111128
112-
```bash
113-
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
114-
```
129+
environment:
130+
WEBPASSWORD_FILE: pihole_webpasswd
115131
116-
#### Docker Compose examples
132+
# lines deleted
117133
118-
Set using a text value.
134+
secrets:
135+
- pihole_webpasswd
136+
restart: unless-stopped
119137
120-
```yaml
121-
...
122-
environment:
123-
FTLCONF_webserver_api_password: 'correct horse battery staple'
138+
secrets:
139+
pihole_webpasswd:
140+
file: ./pihole_password.txt
124141
...
125-
```
142+
```
126143

127-
Set using an [environment variable](https://docs.docker.com/compose/how-tos/environment-variables/) called, for example, `ADMIN_PASSWORD`. The value of `ADMIN_PASSWORD` can be set in the shell of the `docker compose` command or in an `.env` file. See the link above for detailed information.
144+
=== "Docker run"
145+
Set the password inline when launching the container.
128146

129-
```yaml
130-
...
131-
environment:
132-
FTLCONF_webserver_api_password: ${ADMIN_PASSWORD}
133-
...
134-
```
147+
```bash
148+
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
149+
```
135150

136-
Define ADMIN_PASSWORD in shell.
137151

138-
```bash
139-
export ADMIN_PASSWORD=correct horse battery staple
140-
docker compose -f compose.yaml
141-
```
152+
## Configuration Reference
142153

143-
Or define ADMIN_PASSWORD in `.env` file. The `.env` file is placed in the same directory where the Compose yaml file (e.g. `compose.yaml`) is located.
154+
### Optional Variables
144155

145-
```bash
146-
$ cat .env
147-
ADMIN_PASSWORD=correct horse battery staple
148-
$ docker compose -f compose.yaml
149-
```
156+
| Variable | Default | Value | Description |
157+
| :--- | :--- | :--- | :--- |
158+
| `TAIL_FTL_LOG` | `1` | `<0\|1>` | Whether or not to output the FTL log when running the container. Can be disabled by setting the value to 0. |
159+
| `PIHOLE_UID` | `1000` | Number | Overrides image's default pihole user id to match a host user id.<br/>**IMPORTANT**: id must not already be in use inside the container! |
160+
| `PIHOLE_GID` | `1000` | Number | Overrides image's default pihole group id to match a host group id.<br/>**IMPORTANT**: id must not already be in use inside the container! |
150161

151-
### `WEBPASSWORD_FILE` Example
162+
### Advanced Variables
152163

153-
Create a text file called `pihole_password.txt` containing the password in the same directory containing the Compose yaml file (e.g `compose.yaml`).
164+
| Variable | Default | Value | Description |
165+
| :--- | :--- | :--- | :--- |
166+
| `FTL_CMD` | `no-daemon` | `no-daemon -- <dnsmasq option>` | Customize dnsmasq startup options. e.g. `no-daemon -- --dns-forward-max 300` to increase max. number of concurrent dns queries on high load setups. |
167+
| `DNSMASQ_USER` | unset | `<pihole\|root>` | Allows changing the user that FTLDNS runs as. Default: `pihole`, some systems such as Synology NAS may require you to change this to `root`.<br><br>(See [#963](https://github.com/pi-hole/docker-pi-hole/issues/963)) |
168+
| `ADDITIONAL_PACKAGES` | unset | Space separated list of APKs | HERE BE DRAGONS. Mostly for development purposes, this just makes it easier for those of us that always like to have whatever additional tools we need inside the container for debugging. |
154169

155-
```bash
156-
$cat pihole_password.txt
157-
correct horse battery staple
158-
```
170+
### Docker Arguments
159171

160-
Amend compose yaml file with Docker Secrets attributes.
172+
Here is a rundown of other arguments for your docker-compose / docker run.
161173

162-
```yaml
163-
---
164-
# define pihole service
165-
services:
166-
pihole:
167-
container_name: pihole
168-
image: pihole/pihole:latest
174+
| Docker Arguments | Description |
175+
| :--- | :--- |
176+
| `-p <port>:<port>` **Recommended** | Ports to expose (53, 80, 443, 67), the bare minimum ports required for Pi-holes HTTP, HTTPS and DNS services. |
177+
| `--restart=unless-stopped`<br/> **Recommended** | Automatically (re)start your Pi-hole on boot or in the event of a crash. |
178+
| `-v $(pwd)/etc-pihole:/etc/pihole`<br/> **Recommended** | Volumes for your Pi-hole configs help persist changes across docker image updates. |
179+
| `--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. DHCP runs best with `--net=host`, otherwise your router must support dhcp-relay settings. |
180+
| `--cap-add=NET_ADMIN`<br/> _Recommended_ | Commonly added capability for DHCP, see [Note on Capabilities](#note-on-capabilities) below for other capabilities. |
181+
| `--dns=n.n.n.n`<br/> _Optional_ | Explicitly set container's DNS server. It is **_not recommended_** to set this to `localhost`/`127.0.0.1`. |
182+
| `--env-file .env` <br/> _Optional_ | File to store environment variables for docker replacing `-e key=value` settings. Here for convenience. |
169183

170-
# lines deleted
184+
## Note on Capabilities {: #note-on-capabilities }
171185

172-
environment:
173-
WEBPASSWORD_FILE: pihole_webpasswd
186+
Pi-hole's DNS core (FTL) expects to have the following capabilities available:
174187

175-
# lines deleted
188+
- `CAP_NET_BIND_SERVICE`: Allows FTLDNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53)
189+
- `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)
190+
- `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)
191+
- `CAP_SYS_NICE`: FTL sets itself as an important process to get some more processing time if the latter is running low
192+
- `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`
193+
- `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
176194

177-
secrets:
178-
- pihole_webpasswd
179-
restart: unless-stopped
180-
181-
# define pihole_webpasswd secret
182-
secrets:
183-
pihole_webpasswd:
184-
file: ./pihole_password.txt
185-
...
186-
```
195+
This image automatically grants those capabilities, if available, to the FTLDNS process, even when run as non-root.\
196+
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`.\
197+
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.
187198

‎docs/docker/index.md‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -53,20 +53,19 @@ The equivalent command for `docker run` would be:
5353
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
5454
```
5555

56-
## Note On Capabilities
5756

58-
[FTLDNS](https://docs.pi-hole.net/ftldns/) expects to have the following capabilities available:
57+
## Docker tags and versioning
5958

60-
- `CAP_NET_BIND_SERVICE`: Allows FTLDNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53)
61-
- `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)
62-
- `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)
63-
- `CAP_SYS_NICE`: FTL sets itself as an important process to get some more processing time if the latter is running low
64-
- `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`
65-
- `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
59+
The primary docker tags are explained in the following table. [Click here to see the full list of tags](https://hub.docker.com/r/pihole/pihole/tags). See [GitHub Release notes](https://github.com/pi-hole/docker-pi-hole/releases) to see the specific version of Pi-hole Core, Web, and FTL included in the release.
6660

67-
!!! info
68-
This image automatically grants those capabilities, if available, to the FTLDNS process, even when run as non-root.
61+
The Date-based (including incremented "Patch" versions) do not relate to any kind of semantic version number, rather a date is used to differentiate between the new version and the old version, nothing more.
6962

70-
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`.
63+
Release notes will always contain full details of changes in the container, including changes to core Pi-hole components.
7164

72-
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.
65+
| tag | description |
66+
| :--- | :--- |
67+
| `latest` | Always the latest release |
68+
| `2022.04.0` | Date-based release |
69+
| `2022.04.1` | Second release in a given month |
70+
| `*beta` | Early beta releases of upcoming versions - here be dragons |
71+
| `nightly` | Built and pushed whenever there are changes on the `development` branch and additionally produced by the scheduled nightly job. These are the most experimental development images and may change frequently |

0 commit comments

Comments
 (0)