Deploy Pi-hole with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it easy to run Pi-hole as a network-wide DNS-level ad blocker.

This guide walks you through deploying Pi-hole with persistent blocklists, DNS configuration, and HTTPS access to the admin dashboard. Pi-hole acts as a DNS sinkhole that blocks ads and trackers for all devices on your network.

Prerequisites

• A VPS with at least 1 vCPU, 512 MB RAM, and 5 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., pihole.yourdomain.com) with DNS A record pointing to your server's IP
• Port 53 (TCP and UDP) available on the host — no other DNS server can be running

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  pihole:
    image: pihole/pihole:latest
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80/tcp"
    environment:
      - TZ=${TZ:-UTC}
      - FTLCONF_webserver_api_password=${PIHOLE_PASSWORD}
      - FTLCONF_dns_listeningMode=all
    volumes:
      - ../files/pihole-data:/etc/pihole
      - ../files/pihole-dnsmasq:/etc/dnsmasq.d
    healthcheck:
      test: ["CMD-SHELL", "dig +short +norecurse +retry=0 @127.0.0.1 pi.hole || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: Pi-hole requires ports 53 TCP/UDP for DNS resolution. These ports must be free on the host — check that no other DNS resolver (like systemd-resolved) is binding to port 53. The web interface is served on port 8080 to avoid conflicting with Dokploy's port 80.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
PIHOLE_PASSWORD	Web admin interface password	a-strong-password
TZ	Server timezone	America/New_York

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Pi-hole v6+ uses FTLCONF_* environment variables for configuration.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/pihole-data — Pi-hole databases, blocklists, local DNS records, and configuration
• ../files/pihole-dnsmasq — Custom DNSmasq configuration overrides

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/pihole) because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., pihole.yourdomain.com)
3. Set the container port to 80 (Pi-hole's internal web server port)
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Pi-hole container's web interface.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see the pihole container pull and start
3. Check the Logs tab for the pihole service. Look for: FTL started
4. Open https://pihole.yourdomain.com/admin in your browser — you should see the Pi-hole admin dashboard
5. Log in with your PIHOLE_PASSWORD
6. Test DNS resolution by pointing a device's DNS to your server's IP and visiting a known ad domain

Troubleshooting

Port 53 already in use On many Linux systems, systemd-resolved binds to port 53. Disable it with sudo systemctl disable --now systemd-resolved and update /etc/resolv.conf to point to an upstream DNS server (e.g., nameserver 1.1.1.1). Then redeploy Pi-hole.

Web interface not loading Pi-hole's web interface runs on port 80 internally. Ensure Dokploy's domain routing points to the correct container port. If accessing directly (without Dokploy's proxy), use port 8080 as mapped in the compose file.

Slow DNS resolution Check Pi-hole's upstream DNS settings in the admin dashboard under Settings > DNS. By default, Pi-hole uses the DNS servers configured at startup. Ensure the upstream servers (Google 8.8.8.8, Cloudflare 1.1.1.1, etc.) are reachable from the container.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Pi-hole in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Pi-hole.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.