# pi-hole/docker-pi-hole architecture

> Architecture diagram of the GitHub repository pi-hole/docker-pi-hole, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pi-hole/docker-pi-hole
- Repository: https://github.com/pi-hole/docker-pi-hole

## Overview

Docker Pi-hole packages Pi-hole as a container for network-wide DNS blocking. The main workflow is an operator starting the image, which exposes Pi-hole DNS and web access to the network; optional DHCP and NTP roles are also documented. A baked-in cron job periodically refreshes ad lists and flushes logs. The repository tree shows the container entrypoint and cron configuration, but no source excerpts were provided, so internal call relationships and implementation details are not inferred.

Main entry points: [`src/Dockerfile`](https://github.com/pi-hole/docker-pi-hole/blob/master/src/Dockerfile) (Pi-hole image), [`src/crontab.txt`](https://github.com/pi-hole/docker-pi-hole/blob/master/src/crontab.txt) (Cron schedule)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_container["Container runtime"]
  node_container_image["Pi-hole image"]
  node_entrypoint["Container startup<br/>[start.sh]"]
end

subgraph group_maintenance["Scheduled maintenance"]
  node_cron_config["Cron schedule<br/>[crontab.txt]"]
  node_list_refresh["Ad-list refresh"]
  node_log_flush["Log flush"]
end

subgraph group_network["Network services"]
  node_dns["DNS blocking"]
  node_web_ui["Web interface"]
  node_dhcp["DHCP service"]
  node_ntp["NTP service"]
end

node_operator(("Operator"))
node_clients(("Network clients"))
node_persistent_data[("Persistent volumes")]

node_operator -->|"starts with Compose"| node_container_image
node_container_image -->|"provides DNS"| node_dns
node_container_image -->|"exposes web access"| node_web_ui
node_clients -->|"queries"| node_dns
node_operator -->|"configures access"| node_web_ui
node_container_image -->|"mounts volumes"| node_persistent_data
node_container_image -->|"includes cron"| node_cron_config
node_cron_config -->|"schedules weekly"| node_list_refresh
node_cron_config -->|"schedules weekly"| node_log_flush
node_container_image -.->|"optionally provides"| node_dhcp
node_container_image -.->|"optionally provides"| node_ntp

click node_container_image "https://github.com/pi-hole/docker-pi-hole/blob/master/src/Dockerfile"
click node_entrypoint "https://github.com/pi-hole/docker-pi-hole/blob/master/src/start.sh"
click node_cron_config "https://github.com/pi-hole/docker-pi-hole/blob/master/src/crontab.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_container_image,node_entrypoint,node_clients toneBlue
class node_cron_config,node_list_refresh,node_log_flush,node_persistent_data toneAmber
class node_dns,node_web_ui,node_dhcp,node_ntp toneMint
class node_operator toneIndigo
```

## Components

### Container runtime

- [Pi-hole image](https://github.com/pi-hole/docker-pi-hole/blob/master/src/Dockerfile): `src/Dockerfile`
- [Container startup](https://github.com/pi-hole/docker-pi-hole/blob/master/src/start.sh): `src/start.sh`

### Scheduled maintenance

- [Cron schedule](https://github.com/pi-hole/docker-pi-hole/blob/master/src/crontab.txt): `src/crontab.txt`
- **Ad-list refresh**
- **Log flush**

### Network services

- **DNS blocking**
- **Web interface**
- **DHCP service**
- **NTP service**

### Other components

- **Operator**
- **Network clients**
- **Persistent volumes**

## Connections

- Operator → Pi-hole image: starts with Compose (evidence: `README.md`)
- Pi-hole image → DNS blocking: provides DNS (evidence: `README.md`)
- Pi-hole image → Web interface: exposes web access (evidence: `README.md`)
- Network clients → DNS blocking: queries (evidence: `README.md`)
- Operator → Web interface: configures access (evidence: `README.md`)
- Pi-hole image → Persistent volumes: mounts volumes (evidence: `README.md`)
- Pi-hole image → Cron schedule: includes cron (evidence: `README.md`)
- Cron schedule → Ad-list refresh: schedules weekly (evidence: `README.md`)
- Cron schedule → Log flush: schedules weekly (evidence: `README.md`)
- Pi-hole image → DHCP service: optionally provides (evidence: `README.md`)
- Pi-hole image → NTP service: optionally provides (evidence: `README.md`)
