Run Pi-Hole 5 Beta Behind an NGINX Reverse Proxy

January 22, 2020

The team behind the Pi-Hole ad-blocker has released a beta of Pi-Hole v. 5. The two big changes in this beta are (1) the introduction of per-client ad-blocking, and (2) the introduction of a Custom DNS option within the GUI itself. Per-client blocking allows a user to set different rules for, say, his iMac that for, say, his Apple TV. Custom DNS allows a user to set local DNS rules for his network without the need for a workaround. In our view, addition of these features changes Pi-Hole from a tool that primarily blocks ads into an all-around DNS manager that also happens to block ads. Bit by bit, Pi-Hole is making itself indispensable.

The upgrade process went smoothly for us (and it is an upgrade process; you can't install the beta from scratch). Nevertheless, we quickly ran into a series of error messages when trying to make changes through the GUI. Specifically, when trying to whitelist, blacklist, or change the per-client rules, we were met with the following message: "Error, something went wrong! While executing: attempt to write a readonly database":

With some help from the team at Pi-Hole, we discovered that this was the result of our running NGINX as a reverse proxy, instead of using the default lighttpd. This post explains how those who are running both NGINX and Pi-Hole 5 Beta can fix the issue.


For the sake of this guide, we’ll assume that:

  • You are familiar with SSH, with the Raspberry Pi software, with Nginx, and with how reverse proxies work
  • You are already running Pi-Hole

A warning

WAIT The team behind Pi-Hole has made it extremely clear that once an installation has been upgraded to this beta, it cannot be downgraded. Ever. As such, before you start make sure that you have:

  • Made a copy of your Pi’s SD card
  • Backed up the data in Pi-Hole using the Teleporter function in Settings

Do not install this beta if you are operating in a mission critical environment.


To upgrade to the beta, SSH into your Pi and run these three lines:

      echo "release/v5.0" | sudo tee /etc/pihole/ftlbranch
pihole checkout core release/v5.0
pihole checkout web release/v5.0

Because you already have both Pi-Hole and your Nginx reverse proxy set up, you should be able to access the beta in exactly the same way as you accessed the older version.

Fixing Nginx

The error message noted above is caused by a permissions mismatch. Unless you have changed it, the default Nginx user is www-data and the user and group for the Pi-Hole install is pihole:pihole. As such, make changes through the admin interface, we need to add the www-data user into the pihole group.

We can do that by running:

      sudo adduser www-data pihole

Naturally, if you have changed the users or groups at any stage, this will not work. To find out which user Nginx is using, you can run:

      grep user /etc/nginx/nginx.conf

And to find out which user and group Pi-Hole is using, you can run:

      groups pihole

On some systems, a simple reboot of Nginx will suffice to update the permissions and get rid of the errors. In our case, we needed to reboot the Pi completely and to clear the cache in our browser before it worked.


Nginx : 1.14.2
Pi-Hole: 5 Beta
Notice an error?

Have we got something wrong? Please let us know and we’ll fix it right away.


One response to “Run Pi-Hole 5 Beta Behind an NGINX Reverse Proxy

Join the Discussion

Your email address will not be published. Required fields are marked *