Add Some more detailed Docker documentation

docs/docker/build-image.md

@@ -1,4 +1,4 @@
-In case you wish to customise the image, or perhaps check out a branch after being asked by a developer to do so, you can use the convenient `build.sh` script located in the root of the [docker-pi-hole repository](https://github.com/pi-hole/docker-pi-hole)
+In case you wish to customize the image, or perhaps check out a branch after being asked by a developer to do so, you can use the convenient `build.sh` script located in the root of the [docker-pi-hole repository](https://github.com/pi-hole/docker-pi-hole)
 
 ## Checking out the repository
 

docs/docker/configuration.md

@@ -0,0 +1,85 @@
+# Configuration
+
+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`
+
+## Environment Variables
+
+### Recommended Variables
+
+#### `TZ` (Default: `UTC`)
+
+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.
+
+#### `FTLCONF_webserver_api_password` (Default: `unset`)
+
+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.
+
+#### `FTLCONF_dns_upstreams` (Default: `8.8.8.8;8.8.4.4`)
+
+- Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon
+- Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`
+- 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
+
+### Configuring FTL Via The Environment
+
+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
+
+As with the recommended examples above for the web password and DNS upstreams, the syntax is `FTLCONF_[section_][setting]`
+
+Given the below `toml` formatted example from `pihole.toml`, we can translate this to the environment variable `FTLCONF_dns_dnssec`
+
+```toml
+[dns]
+  dnssec = true
+```
+
+!!! note
+    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
+
+
+An example of how some of these variables may look in your compose file
+
+```yaml
+    environment:
+      TZ: europe/London
+      FTLCONF_dns_revServers: 'true,192.168.0.0/16,192.168.0.1,lan'
+      FTLCONF_dns_upstreams: '8.8.8.8;8.8.4.4'
+      FTLCONF_webserver_api_password: 'correct horse battery staple'
+      FTLCONF_webserver_port: '8082,443s'
+      FTLCONF_debug_api: 'true'
+```
+
+### Other Variables
+
+#### `TAIL_FTL_LOG` (Default: `1`)
+
+Whether or not to output the FTL log when running the container. Can be disabled by setting the value to 0
+
+#### `PIHOLE_UID` (Default: `100`)
+
+Overrides image's default pihole user id to match a host user id
+
+#### `PIHOLE_GID` (Default: `100`)
+
+Overrides image's default pihole group id to match a host group id
+
+!!! Warning
+    For the above two settings, the `id` must not already be in use inside the container!
+
+#### `FTL_CMD` (Default: `no-daemon`)
+
+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.
+
+#### `DNSMASQ_USER` (Default: `pihole`)
+
+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))
+
+#### `ADDITIONAL_PACKAGES` (Default: unset)
+
+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.
+
+Adding packages here is the same as running `apk add <package>` inside the container
+
+#### `PH_VERBOSE` (Default: `0`)
+
+Setting this environment variable to `1` will set `-x`, making the scripts that run on container startup more verbose. Useful for debugging only.

docs/docker/index.md

@@ -0,0 +1,66 @@
+The easiest way to get up and running with Pi-hole on Docker is to use our quick-start `docker-compose.yml` template.
+
+Copy the below [Docker Compose](https://docs.docker.com/compose/) example and customize as needed
+
+```yaml
+# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
+services:
+  pihole:
+    container_name: pihole
+    image: pihole/pihole:latest
+    ports:
+      # DNS Ports
+      - "53:53/tcp"
+      - "53:53/udp"
+      # Default HTTP Port
+      - "80:80/tcp"
+      # Default HTTPs Port. FTL will generate a self-signed certificate
+      - "443:443/tcp"
+      # Uncomment the below if using Pi-hole as your DHCP Server
+      #- "67:67/udp"
+    environment:
+      # Set the appropriate timezone for your location from
+      # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, e.g:
+      TZ: 'Europe/London'
+      # Set a password to access the web interface. Not setting one will result in a random password being assigned
+      FTLCONF_webserver_api_password: 'correct horse battery staple'
+      # If using Docker's default `bridge` network setting the dns listening mode should be set to 'all'3
+      FTLCONF_dns_listeningMode: 'all'
+    # Volumes store your data between container upgrades
+    volumes:
+      # For persisting Pi-hole's databases and common configuration file
+      - './etc-pihole:/etc/pihole'
+      # For persisting custom dnsmasq config files. Most will not need this, and can be safely removed/commented out
+      - './etc-dnsmasq.d:/etc/dnsmasq.d'
+    cap_add:
+      # Required if you are using Pi-hole as your DHCP server, else not needed
+      # See Note On Capabilities below
+      - NET_ADMIN
+    restart: unless-stopped
+```
+
+Run `docker compose up -d` to build and start Pi-hole (on older systems, the syntax here may be `docker-compose up -d`)
+
+The equivalent command for `docker run` would be:
+
+```
+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
+```
+
+## Note On Capabilities
+
+[FTLDNS](https://docs.pi-hole.net/ftldns/in-depth/#linux-capabilities) expects to have the following capabilities available:
+
+- `CAP_NET_BIND_SERVICE`: Allows FTLDNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53)
+- `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)
+- `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)
+- `CAP_SYS_NICE`: FTL sets itself as an important process to get some more processing time if the latter is running low
+- `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`
+- `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
+
+!!! info
+    This image automatically grants those capabilities, if available, to the FTLDNS process, even when run as non-root.
+
+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`.
+
+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.

docs/docker/upgrading/index.md

@@ -0,0 +1,31 @@
+# Upgrading
+
+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. However, mounting these configuration files as read-only should be avoided. Volumes are also important to persist the configuration in case you have removed the Pi-hole container which is a typical docker upgrade pattern.
+
+!!! tip "Always Read The Release Notes!"
+    Ensure you read the release notes for both the Docker Release and the main Pi-hole component releases. This will help you avoid common problems due to known issues with upgrading or newly required arguments or variables
+
+## Upgrading / Reconfiguring
+
+!!! Note
+    The normal Pi-hole functions to upgrade (`pihole -up`) or reconfigure (`pihole -r`) are disabled within the docker container. New images will be released, and you can upgrade by replacing your old container with a fresh upgraded image, which is more in line with 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.
+
+### Docker Compose
+
+Navigate to the directory in which your `docker-compose.yml` file exists and run the following commands
+
+```bash
+docker compose down
+docker compose pull
+docker compose up -d
+```
+
+### Docker run
+
+```bash
+docker stop pihole
+docker rm pihole
+docker pull pihole/pihole:latest
+docker run [ ... arguments (see Getting Started) ... ]
+```
+

docs/docker/upgrading/v5-v6.md

@@ -0,0 +1,85 @@
+!!! info
+    The last image of the Pi-hole docker container which contained v5.x Pi-hole components was [`2024.07.0`](https://github.com/pi-hole/docker-pi-hole/releases/tag/2024.07.0)
+    <br><br>
+    Versions after this will be based on v6.x Pi-hole components.
+
+## Changed Environment Variables
+
+Nearly all environment variables from previous versions have been removed, but functionality can be replicated by setting their `FTLCONF_` equivalent instead. (See [Configuration](../configuration.md#configuring-ftl-via-the-environment) page for more details)
+
+### Misc
+
+| Old Variable | New Variable |
+|:-------------|:-------------|
+|`CUSTOM_CACHE_SIZE`|`FTLCONF_dns_cache_size`|
+|`DNS_BOGUS_PRIV`|`FTLCONF_dns_bogusPriv`|
+|`DNS_FQDN_REQUIRED`|`FTLCONF_dns_domainNeeded`|
+|`DNSMASQ_LISTENING`|`FTLCONF_dns_listeningMode`|
+|`DNSSEC`|`FTLCONF_dns_dnssec`|
+|`INTERFACE`|`FTLCONF_dns_interface`|
+|`PIHOLE_DNS_`|`FTLCONF_dns_upstreams`|
+|`QUERY_LOGGING`|`FTLCONF_dns_queryLogging`|
+|`WEBPASSWORD`|`FTLCONF_webserver_api_password`|
+|`WEB_PORT`|`FTLCONF_webserver_port`|
+|`WEBTHEME`|`FTLCONF_webserver_interface_theme`|
+|`WEBUIBOXEDLAYOUT`|`FTLCONF_webserver_interface_boxed`|
+
+### DHCP Variables
+
+|Old|New|
+|:--|:--|
+|`DHCP_ACTIVE`| `FTLCONF_dhcp_active`|
+|`DHCP_START`| `FTLCONF_dhcp_start`|
+|`DHCP_END`| `FTLCONF_dhcp_end`|
+|`DHCP_ROUTER`| `FTLCONF_dhcp_router`|
+|`DHCP_LEASETIME`| `FTLCONF_dhcp_leaseTime`|
+|`PIHOLE_DOMAIN`| `FTLCONF_dns_domain`|
+|`DHCP_IPv6`| `FTLCONF_dhcp_ipv6`|
+|`DHCP_rapid_commit`| `FTLCONF_dhcp_rapidCommit`|
+
+### Conditional Forwarding Variables
+
+Reverse server (`REV_SERVER*`) variables should be replaced with the single `FTLCONF_dns_revServers`, which accepts an array of reverse servers (delimited by `;`) in the following format:
+
+```
+<enabled>,<ip-address>[/<prefix-len>],<server>[#<port>],<domain>
+```
+
+If, for example, you had the following old style variables:
+
+- `REV_SERVER: 'true'`
+- `REV_SERVER_DOMAIN: 'lan'`
+- `REV_SERVER_TARGET: '192.168.0.1#53'`
+- `REV_SERVER_CIDR: '192.168.0.0/24'`
+
+You would now set:
+
+```
+FTLCONF_dns_revServers: 'true,192.168.0.0/24,192.168.0.1#53,lan'
+```
+
+### Removed Variables
+
+The following variables can be removed without replacement, as they are no longer used:
+
+- `CONDITIONAL_FORWARDING`
+- `CONDITIONAL_FORWARDING_DOMAIN`
+- `CONDITIONAL_FORWARDING_IP`
+- `CONDITIONAL_FORWARDING_REVERSE`
+- `CORS_HOSTS`
+- `DNS1`
+- `DNS2`
+- `FTLCONF_REPLY_ADDR4`
+- `FTLCONF_REPLY_ADDR6`
+- `IPV6`
+- `ServerIP`
+- `ServerIPv6`
+- `SKIPGRAVITYONBOOT`
+- `TEMPERATUREUNIT`
+- `VIRTUAL_HOST`
+- `WEB_BIND_ADDR`
+- `WEB_GID`
+- `WEB_UID`
+- `WEBLOGS_STDOUT`
+- `WEBPASSWORD_FILE`
+

mkdocs.yml

@@ -159,6 +159,11 @@ nav:
     - "Pi-hole extensions": regex/pi-hole.md
     - "Approximate matching": regex/approximate.md
   - 'Docker':
+    - 'Docker': docker/index.md
+    - 'Configuration': docker/configuration.md
+    - 'Upgrading':
+      - 'Upgrading': docker/upgrading/index.md
+      - 'Upgrading from v5.x': docker/upgrading/v5-v6.md
     - 'Building': docker/build-image.md
     - 'DHCP': docker/DHCP.md
   - 'Contributing':