RPi-PiHole Docker Stack

Docker compose files for Raspberry Pi 3 running DNS and related services.

Docker Compose Stack Structure

The monolithic docker-compose.yml has been split into separate compose files organized by service category.

Directory Structure

Each subdirectory contains a docker-compose.yml file with related services:

DNS & Network

• pihole/ - DNS services (unbound, pihole)
  • unbound - Recursive DNS resolver
  • pihole - DNS sinkhole for ad-blocking (depends on unbound)

Docker Management

• docker-management/ - Docker management tools (socket-proxy, tugtainer)

Monitoring & Management

• checkmate-capture/ - System metrics capture

Messaging

• mqtt/ - Eclipse Mosquitto MQTT broker

Usage

Managing All Services

Use the manage-services.sh script to control all service groups at once:

# Initialize all bind mount directories
./manage-services.sh init

# Start all services
./manage-services.sh start

# Stop all services
./manage-services.sh stop

# Restart all services
./manage-services.sh restart

# Check status of all services
./manage-services.sh status

# Pull latest images for all services
./manage-services.sh pull

Managing Specific Services

You can also manage individual service groups:

# Start only DNS services
./manage-services.sh start pihole

# Check status of watchtower
./manage-services.sh status watchtower

# Initialize bind mounts for MQTT only
./manage-services.sh init mqtt

The script will:

• Iterate through specified subdirectories (or all if none specified)
• Execute the specified action on each service group
• Display progress and a summary with success/failure counts
• Exit with error if any service group fails

Managing Individual Service Groups Manually

Start services in a specific category:

cd <service-directory>
docker compose up -d

Stop services in a specific category:

cd <service-directory>
docker compose down

View logs for a specific service group:

cd <service-directory>
docker compose logs -f

Network Configuration

Pi-hole Network

• Network: 172.24.3.0/24
• Unbound IP: 172.24.3.53
• Pi-hole IP: 172.24.3.52
• Docker Socket Proxy IP: 172.24.3.3

Macvlan Bridge Setup

The macvlan_bridge.sh script can be used to set up a macvlan bridge for Docker networking. Edit the variables at the top of the script to match your network configuration before running:

# Edit the script with your network settings
nano macvlan_bridge.sh

# Run the script (requires root)
sudo ./macvlan_bridge.sh

Data Volumes

All persistent data is stored in the ../data directory (one level up from the repository root). This keeps the configuration files separate from the data.

Expected data structure:

data/
├── pihole/
├── dnsmasq.d/
├── unbound/
│   └── unbound.conf
├── mosquitto/
│   ├── config/
│   ├── data/
│   └── log/
├── pihole.env
├── watchtower.env
└── checkmate-capture.env

Service Dependencies

Services are grouped by their dependencies:

• pihole/ contains both unbound and pihole because Pi-hole depends on Unbound as its upstream DNS resolver
• All other services are independent and can be started/stopped individually

Backup

The original monolithic docker-compose.yml has been saved as docker-compose.yml.backup.

Port Mappings

Service	Port(s)	Protocol	Description
Pi-hole	53	TCP/UDP	DNS
Pi-hole	80	TCP	Web Interface
Unbound	5253	TCP/UDP	DNS (internal)
Watchtower	8082	TCP	Web UI
Docker Socket Proxy	2375	TCP	Docker API
Checkmate Capture	59232	TCP	Metrics API
MQTT Broker	1883	TCP	MQTT