Use Pi-Hole with NGINX for HTTPS WebGUI Access

The default installation of Pi-Hole gives you an option to use the lighttpd webserver, which is a very lightweight webserver option, but it does not give you the option to enable or use HTTPS for accessing the WebGUI.

We can force the local Pi-Hole installation to use HTTPS with the help of NGINX.

This setup is a community-created setup, and is not officially supported by the Pi-Hole team. More information can be found here: https://docs.pi-hole.net/guides/webserver/nginx/

Prerequisite

If you have already installed Pi-Hole on your system and chose to use lighttpd, run the following command to stop lighttpd and uninstall it:

#Stop lighttpd
sudo service lighttpd stop

#Stop lighttpd from starting at boot
sudo systemctl disable lighttpd

#Remove lighttpd
sudo apt purge lighttpd

Install PHP 8.1 Packages

If your base OS system (Debian 11 in my case) does not have the latest PHP repository, you can manually add the popular https://packages.sury.org/php/ PHP repository to your system.

Install gnupg to allow adding PHP 8.1 repository to the system.

sudo apt install gnupg

Add PHP repository and update package list.

echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
wget -qO - https://packages.sury.org/php/apt.gpg | sudo apt-key add -
sudo apt update

Install required PHP packages for Pi-Hole. We will be using the latest PHP 8.1 versions.

sudo apt install php8.3-fpm php8.3-cgi php8.3-xml php8.3-sqlite3 php8.3-intl

Enable PHP FPM at startup.

sudo systemctl enable php8.3-fpm

Install NGINX

sudo apt install nginx

Configure NGINX

Unlink the default config

sudo unlink /etc/nginx/sites-enabled/default

Using your preferred text edit, create a config file in /etc/nginx/sites-available/

#create config modules into /etc/nginx/sites-available
sudo nano /etc/nginx/sites-available/pihole

Modify the following NGINX config to suit your server, and paste it into the config file:

server {
	#Listen on HTTPS and your FQDN
	listen 443 ssl;
    server_name your_Pi_Hole_Server_FQDN.example;
    
	root /var/www/html;
	autoindex off;
	error_page 404 /pihole/index.php;
	index pihole/index.php index.php index.html index.htm;

	#Your SSL Cert Locations
	ssl_certificate /etc/ssl/certs/your_SSL_cert;
	ssl_certificate_key /etc/ssl/private/your_SSL_cert_private_key;

    #Disable NGINX current version reporting on error pages
	server_tokens off;
  
	#Force Strong Encryptions
	ssl_protocols	TLSv1.3;
	ssl_prefer_server_ciphers	on;
	ssl_ciphers "EECDH+ECDSA+AESGCM EECDH+aRSA+AESGCM EECDH+ECDSA+SHA384 EECDH+ECDSA+SHA256 EECDH+aRSA+SHA384 EECDH+aRSA+SHA256 EECDH+aRSA+RC4 EECDH EDH+aRSA HIGH !RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP !PSK !SRP !DSS";

	location / {
		expires max;
		try_files $uri $uri/ =404;
	}

	#Match this to your PHP FPM Version
	location ~ \.php$ {
		include fastcgi_params;
		fastcgi_param SCRIPT_FILENAME $document_root/$fastcgi_script_name;
		fastcgi_pass unix:/run/php/php8.3-fpm.sock;
		fastcgi_param FQDN true;
	}

	location /*.js {
		index pihole/index.js;
	}

	location /admin {
		root /var/www/html;
		index index.php index.html index.htm;
	}

	location ~ /\.ht {
	deny all;
	}
}

Link the config file from /etc/nginx/sites-available to /etc/nginx/sites-enabled

#Link /etc/nginx/sites-available to  /etc/nginx/sites-enabled
sudo ln -s /etc/nginx/sites-available/pihole /etc/nginx/sites-enabled/pihole

Enable NGINX to start on boot

sudo systemctl enable nginx

Change the ownership and permission of the /var/www/html folder

#Change ownership and permission
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html

Grant pihole user the www-data group to allow it access to the Pi-Hole folders and databases

sudo usermod -aG pihole www-data

Test your site

Once done, you can now navigate to the HTTPS version of your Pi-Hole server, and will see that connection is secure.