Skip to content

Commit db94113

Browse files
buckaroogeekbuckaroogeek
committed
Add notes on setting web interface password
Adds notes on setting web interface password using the FTLCONF_webserver_api_password environment variable or the WEBPASSWORD_FILE environment variable. Examples are provided. Signed-off-by: Bradley G Smith <[email protected]>
1 parent f47ded3 commit db94113

File tree

1 file changed

+106
-17
lines changed

1 file changed

+106
-17
lines changed

‎docs/docker/configuration.md

+106-17
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,6 @@ The recommended way to configure the Pi-hole docker container is by utilizing [e
44

55
## Environment Variables
66

7-
### Recommended Variables
8-
9-
#### `TZ` (Default: `UTC`)
10-
11-
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.
12-
13-
#### `FTLCONF_webserver_api_password` (Default: `unset`)
14-
15-
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.
16-
17-
#### `FTLCONF_dns_upstreams` (Default: `8.8.8.8;8.8.4.4`)
18-
19-
- Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon
20-
- Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`
21-
- 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
22-
237
### Configuring FTL Via The Environment
248

259
While FTL's configuration file can be manually edited, set via the CLI (`pihole-FTL --config setting.name=value`), or set via the web interface - the recommended approach is to do this via environment variables
@@ -38,7 +22,6 @@ Array type configs should be delimited with `;`
3822
!!! note
3923
All FTL settings that are set via environment variables effectively become read-only, meaning that you will not be able to change them via the web interface or CLI. This is to ensure a "single source of truth" on the config. If you later unset or remove an environment variable, then FTL will revert to the default value for that setting
4024

41-
4225
An example of how some of these variables may look in your compose file
4326

4427
```yaml
@@ -51,6 +34,22 @@ An example of how some of these variables may look in your compose file
5134
FTLCONF_debug_api: 'true'
5235
```
5336
37+
### Recommended Variables
38+
39+
#### `TZ` (Default: `UTC`)
40+
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.
42+
43+
#### `FTLCONF_webserver_api_password` (Default: `unset`)
44+
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.
46+
47+
#### `FTLCONF_dns_upstreams` (Default: `8.8.8.8;8.8.4.4`)
48+
49+
- Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon
50+
- Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`
51+
- 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
52+
5453
### Other Variables
5554

5655
#### `TAIL_FTL_LOG` (Default: `1`)
@@ -85,3 +84,93 @@ Adding packages here is the same as running `apk add <package>` inside the conta
8584
#### `PH_VERBOSE` (Default: `0`)
8685

8786
Setting this environment variable to `1` will set `-x`, making the scripts that run on container startup more verbose. Useful for debugging only.
87+
88+
#### `WEBPASSWORD_FILE` (Default: unset)
89+
90+
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.
91+
92+
## Notes On Web Interface Password
93+
94+
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/).
95+
96+
### `FTLCONF_webserver_api_password` Examples
97+
98+
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.
99+
100+
#### Docker run example
101+
102+
```bash
103+
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
104+
```
105+
106+
#### Docker Compose examples
107+
108+
Set using a text value.
109+
110+
```yaml
111+
...
112+
environment:
113+
FTLCONF_webserver_api_password: 'correct horse battery staple'
114+
...
115+
```
116+
117+
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.
118+
119+
```yaml
120+
...
121+
environment:
122+
FTLCONF_webserver_api_password: ${ADMIN_PASSWORD}
123+
...
124+
```
125+
126+
Define ADMIN_PASSWORD in shell.
127+
128+
```bash
129+
export ADMIN_PASSWORD=correct horse battery staple
130+
docker compose -f compose.yaml
131+
```
132+
133+
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.
134+
135+
```bash
136+
$ cat .env
137+
ADMIN_PASSWORD=correct horse battery staple
138+
$ docker compose -f compose.yaml
139+
```
140+
141+
### `WEBPASSWORD_FILE` Example
142+
143+
1. Create a text file called `pihole_password.txt` containing the password in the same directory containing the Compose yaml file (e.g `compose.yaml`).
144+
145+
```bash
146+
$cat pihole_password.txt
147+
correct horse battery staple
148+
```
149+
150+
1. Amend compose yaml file with Docker Secrets attributes.
151+
152+
```yaml
153+
---
154+
# define pihole service
155+
services:
156+
pihole:
157+
container_name: pihole
158+
image: pihole/pihole:latest
159+
160+
# lines deleted
161+
162+
environment:
163+
WEBPASSWORD_file: pihole_webpasswd
164+
165+
# lines deleted
166+
167+
secrets:
168+
- pihole_webpasswd
169+
restart: unless-stopped
170+
171+
# define pihole_webpasswd secret
172+
secrets:
173+
pihole_webpasswd:
174+
file: ./pihole_password.txt
175+
...
176+
```

0 commit comments

Comments
 (0)