Skip to content

Commit 444c2c1

Browse files
PromoFauxPromoFaux
authored
Merge pull request #1182 from buckaroogeek/webpassword
Add notes on setting web interface password
2 parents e857a2d + bcf85de commit 444c2c1

File tree

1 file changed

+107
-16
lines changed

1 file changed

+107
-16
lines changed

‎docs/docker/configuration.md

Lines changed: 107 additions & 16 deletions
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
@@ -50,6 +34,22 @@ An example of how some of these variables may look in your compose file
5034
FTLCONF_debug_api: 'true'
5135
```
5236
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+
5353
### Other Variables
5454

5555
#### `TAIL_FTL_LOG` (Default: `1`)
@@ -85,8 +85,99 @@ Adding packages here is the same as running `apk add <package>` inside the conta
8585

8686
Setting this environment variable to `1` will set `-x`, making the scripts that run on container startup more verbose. Useful for debugging only.
8787

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+
8892
### Variable Formatting
8993

9094
Environment variables may be set in the format given here, or they may be entirely uppercase in the conventional manner.
9195

9296
For example, both `FTLCONF_dns_upstreams` and `FTLCONF_DNS_UPSTREAMS` are functionally equivalent when used as environment variables.
97+
98+
## Notes On Web Interface Password
99+
100+
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/).
101+
102+
### `FTLCONF_webserver_api_password` Examples
103+
104+
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.
105+
106+
#### Docker run example
107+
108+
```bash
109+
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
110+
```
111+
112+
#### Docker Compose examples
113+
114+
Set using a text value.
115+
116+
```yaml
117+
...
118+
environment:
119+
FTLCONF_webserver_api_password: 'correct horse battery staple'
120+
...
121+
```
122+
123+
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.
124+
125+
```yaml
126+
...
127+
environment:
128+
FTLCONF_webserver_api_password: ${ADMIN_PASSWORD}
129+
...
130+
```
131+
132+
Define ADMIN_PASSWORD in shell.
133+
134+
```bash
135+
export ADMIN_PASSWORD=correct horse battery staple
136+
docker compose -f compose.yaml
137+
```
138+
139+
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.
140+
141+
```bash
142+
$ cat .env
143+
ADMIN_PASSWORD=correct horse battery staple
144+
$ docker compose -f compose.yaml
145+
```
146+
147+
### `WEBPASSWORD_FILE` Example
148+
149+
Create a text file called `pihole_password.txt` containing the password in the same directory containing the Compose yaml file (e.g `compose.yaml`).
150+
151+
```bash
152+
$cat pihole_password.txt
153+
correct horse battery staple
154+
```
155+
156+
Amend compose yaml file with Docker Secrets attributes.
157+
158+
```yaml
159+
---
160+
# define pihole service
161+
services:
162+
pihole:
163+
container_name: pihole
164+
image: pihole/pihole:latest
165+
166+
# lines deleted
167+
168+
environment:
169+
WEBPASSWORD_file: pihole_webpasswd
170+
171+
# lines deleted
172+
173+
secrets:
174+
- pihole_webpasswd
175+
restart: unless-stopped
176+
177+
# define pihole_webpasswd secret
178+
secrets:
179+
pihole_webpasswd:
180+
file: ./pihole_password.txt
181+
...
182+
```
183+

0 commit comments

Comments
 (0)