Skip to content

Setting Up Pi-hole Exporter with Docker Compose

Introduction to PiHole Exporter

PiHole Exporter is a monitoring tool designed to export PiHole metrics for use with Prometheus and Grafana. This guide covers deploying PiHole Exporter using Docker Compose, configuring required environment variables, and integrating it with Prometheus for effective monitoring and visualization.

Requirements

  • PiHole v6 (latest version)
  • Prometheus and Grafana installed and configured (Note: Prometheus could also be running via Docker)

Creating the Docker Compose File

Create a directory for your PiHole Exporter deployment and navigate into it:

mkdir -p /home/<user>/docker/pihole-exporter
cd /home/<user>/docker/pihole-exporter

Replace <user> with your system username (e.g., techdox).

Create a file named docker-compose.yml with the following content:

services:
  pihole-exporter:
    image: ekofr/pihole-exporter:latest
    ports:
      - "9617:9617"
    environment:
      PIHOLE_HOSTNAME: "192.168.68.104" # IP address of your PiHole
      PIHOLE_PASSWORD: "password" # PiHole web admin password

Avoid storing credentials in compose files

The PIHOLE_PASSWORD is stored in plain text in the compose file. If you commit this file to a public repository, your Pi-hole password will be exposed. Use a .env file for sensitive values and add .env to your .gitignore.

Configuration Details

  • PIHOLE_HOSTNAME: IP address or hostname of your PiHole installation.
  • PIHOLE_PASSWORD: Password for your PiHole web interface.

Deploying PiHole Exporter

Navigate to your deployment directory and run Docker Compose:

cd /home/<user>/docker/pihole-exporter
docker compose up -d

This command pulls the PiHole Exporter image, creates, and starts the container.

Integrating with Prometheus

To visualize the exported metrics, add PiHole Exporter to your Prometheus scrape jobs by updating your Prometheus configuration:

scrape_configs:
  - job_name: 'pihole-exporter'
    static_configs:
      - targets: ['<exporter-host>:9617']

Replace <exporter-host> with your server’s IP address or hostname where PiHole Exporter is running.

After updating, restart Prometheus to apply changes:

sudo systemctl restart prometheus
or 
docker restart prometheus

Visualizing Data with Grafana

Import the Pi-hole Exporter dashboard (ID: 10176) into Grafana:

  1. In Grafana, go to Dashboards → Import
  2. Enter dashboard ID 10176
  3. Select your Prometheus data source
  4. Click Import

Accessing PiHole Exporter

Ensure PiHole Exporter is running by accessing:

http://localhost:9617/metrics

Replace localhost with your server's IP or hostname if accessing remotely.

Conclusion

By following this guide, you've successfully deployed PiHole Exporter with Docker Compose, integrated it with Prometheus, and are ready to visualize metrics in Grafana.

If there is an issue with this guide or you wish to suggest changes, please raise an issue on GitHub.