Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/damianiglesias/pihole-ubuntu-deploy/llms.txt

Use this file to discover all available pages before exploring further.

Pi-hole Ubuntu Deploy is an open-source automation project that turns any Ubuntu Server — whether a virtual machine, a Raspberry Pi, or a repurposed old PC — into a network-wide DNS-level ad and telemetry blocker. Instead of fighting trackers browser-by-browser, Pi-hole intercepts DNS queries for every device on your LAN and silently drops requests to known ad, telemetry, and malware domains before they ever leave your network. This project wraps Pi-hole v6’s official installer in a single opinionated Bash script (and an optional Ansible + Docker path) that handles all the messy setup work for you: freeing port 53, installing dependencies, injecting advanced blocklists, configuring a static IP via Netplan, hardening the firewall with UFW, and optionally layering on Unbound recursive DNS, the PADD terminal dashboard, a Python DNS manager, and Log2Ram disk optimization — all from one sudo ./deploy.sh command.

​
Deployment Methods

Bash Script

Install Pi-hole and all optional components directly on the OS. Best for dedicated hardware like a Raspberry Pi or a bare-metal Ubuntu server.

Ansible + Docker

Deploy the full Pi-hole stack inside Docker containers using an Ansible playbook. Ideal for reproducible, version-controlled infrastructure.

Unbound DNS

Add a local recursive DNS resolver so your Pi-hole never relies on a third-party upstream. Queries are resolved from the root nameservers directly.

PADD Dashboard

A terminal-based statistics dashboard that shows live Pi-hole metrics directly in your SSH session — no browser required.

​
Key Features

One-Command Pi-hole v6 Install

Run sudo ./deploy.sh and the script handles everything: port 53 liberation, dependency installation, and the official Pi-hole v6 installer — no manual steps required.

Optional Unbound Recursive DNS

Optionally install Unbound as a local recursive resolver listening on 127.0.0.1#5335, removing any dependency on upstream DNS providers like Google or Cloudflare.

PADD Terminal Dashboard

Install PADD to get a rich, auto-refreshing terminal dashboard showing query counts, block rates, and client activity. Can be configured to launch automatically on SSH login.

Python DNS Manager

A Python-based tool (cloned from Codeberg) that syncs custom local DNS records into Pi-hole via its API. Manage hostnames in a plain entries.txt file.

Log2Ram Disk Optimization

Optionally install Log2Ram to redirect Pi-hole’s high-frequency log writes to a RAM-backed tmpfs, dramatically reducing disk wear — especially valuable on SD cards and VM images.

Automated UFW Firewall Setup

The script automatically enables UFW and opens only the ports Pi-hole needs: TCP 22 (SSH), TCP 80 (web interface), and port 53 (DNS). Everything else stays closed.

Netplan Static IP Configuration

Avoid DNS disruptions caused by DHCP lease changes. The installer detects your network interface and current IP, then writes a permanent Netplan configuration to lock them in.

Advanced Blocklist Injection

With a single [y/n] prompt, inject three battle-tested blocklists directly into Pi-hole’s SQLite gravity database: StevenBlack Unified Hosts, AdGuard Mobile, and EasyPrivacy Tracking.
Unbound is included in the installer but is currently experimental and may not function correctly in all environments. Manual post-install configuration is likely required. See the Unbound component page for current status and workaround instructions.

​
Project Structure

The repository is organized as follows: 
pihole-ubuntu-deploy/
├── deploy.sh                        # Main Bash installer (v4.1)
├── ansible/
│   ├── install_pihole.yml           # Ansible playbook for Docker-based deployment
│   └── inventory.ini                # Ansible inventory (target hosts)
├── tools/
│   └── piholedns                    # Python DNS Manager CLI tool
└── legacy_scripts/                  # Older or experimental script versions
File / DirectoryPurpose
deploy.shThe primary all-in-one Bash installer. Runs interactively and handles every setup step.
ansible/install_pihole.ymlAnsible playbook that deploys Pi-hole via Docker Compose on a remote or local Ubuntu host.
ansible/inventory.iniDefines the target host(s) for the Ansible playbook.
tools/piholednsWrapper script for the Python DNS Manager. Run with sudo ./piholedns from the tools/ directory.
legacy_scripts/Archived earlier versions of the installer kept for reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us