Skip to content
Automated Self-Updating (Public) Pi-hole Stack using unbound as recursive DNS server with Ansible
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
files Fix Bus Error Jun 16, 2019
LICENSE Initial commit Jun 7, 2019 Update README Jun 7, 2019
ansible.cfg Initial commit Jun 7, 2019
hosts Initial commit Jun 7, 2019
playbook.yml Remove A query from fail2ban regex Jul 21, 2019
requirements.yml Initial commit Jun 7, 2019

Automated, self-updating, Pi-hole stack using unbound as recursive DNS server

This Ansible playbook installs a self updating Pi-hole stack from scratch:

  • You can choose between a Public Pi-hole or a Personal/Private one
  • Both use unbound as recursive DNS server instead of public upstream DNS servers
  • Both deploy (by default) the uber adlist/blocklist by
  • Both add my (auto-updated) whitelist for your websurfing convenience
  • If deploying a public Pi-hole, it includes LetsEncrypt to secure the admin interface with valid certificate over HTTPS
  • If deploying a public Pi-hole, basic protection against DNS Amplification, SSH and bruteforce attacks is included using fail2ban
  • The entire stack is based on Docker (so OpenVZ VPSes are NOT supported)

Tested on Ubuntu Server 18.04.2 LTS (Minimal) with Ansible 2.8 on

Proposed Usecase

I designed this playbook for my own personal usecase and decided to make it public for those of you who have the same usecase and/or want to (re)use specific parts from my playbook.
I'm willing to learn how to make this playbook more robust and generic. Therefore I am accepting pull requests :)
I highly recommend checking the playbook before running so that you know what will be installed etc.

Remarks for Public installation

  • Please do not set up a PUBLIC Pi-hole if you don't know what you're doing. You risk getting in all sorts of trouble. Most ISPs don't allow a public DNS resolver on their networks and will shut you down without notice. Why? Because it's generally a bad idea. You have been warned.
  • Make sure to add an A (and if applicable, AAAA) record for your Pi-hole's hostname in your domainname's DNS, pointing to the IP address of your server.
  • If certificate generation fails, click here for troubleshooting steps

Installation Instructions

  1. Install Ansible
  2. Clone repository using git clone
  3. Edit hosts and .env file to reflect your setup, i.e. change domains, IP etc. playbook.yml does NOT need to be changed!
  4. Install required roles from Ansible Galaxy roles using ansible-galaxy install -r requirements.yml
  5. Start playbook using ansible-playbook playbook.yml --ask-become-pass
    When running the playbook on a remote target/server, make sure to copy your SSH key to remote target/server first (before running the playbook) using ssh-copy-id

Usage Instructions

Once everything has been installed, you can use regular docker and docker-compose commands to stop/start/restart containers.
The docker-compose.yml file will be located at /opt/automated-pihole after installation.

Uninstallation Instructions

  1. sudo docker-compose -f /opt/automated-pihole/docker-compose.yml down
  2. rm -rf /opt/automated-pihole
  3. Consult playbook.yml to manually review packages & firewall rules that are no longer needed


  • Even though this playbook configures and automatic updating Pi-hole, the Pi-Hole developers specifically have not included an auto-update option. It is best to read the release notes and determine if an update is appropriate for you, prior to updating. Sometimes updates can introduce breaking changes requiring manual intervention, such as editing/updating the docker-compose file. Therefore always keep an eye on the release notes.
  • This playbook/script/repository is 100% unofficial and NOT affiliated with, funded, endorsed, or in any way associated with Pi-hole.



Unless otherwise specified, all code is released under the GNU General Public License v3.0. See the repository's LICENSE file for details.

Licenses for other components

You can’t perform that action at this time.