Skip to main content

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

Screenshot 2022-11-01 001802.png

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

Screenshot 2022-11-01 001923.png

Add Sury PHP repository and update package list.

#Get the repo keyring
curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb

#Install the repo keyring
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb

#Add the Sury PHP repo to apt source
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'

#Update the repo
sudo apt update

Screenshot_2024-04-28_001912.png

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

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

Screenshot 2022-11-01 003259.png

Enable PHP FPM at startup.

sudo systemctl enable php8.3-fpm

Screenshot 2022-11-01 003459.png

Install NGINX
sudo apt install nginx

Screenshot 2022-11-01 003814.png

Configure NGINX

Screenshot 2022-11-01 141621.png

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;
	}
}

Screenshot 2022-11-01 144437.png

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

Screenshot 2022-11-01 150323.png

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.

Screenshot 2022-11-01 161007.png