Setting up Custom Hostname Forwarding On Your Home Network with Nginx Proxy Manager and Pi-Hole
Tags: nginx, pihole, docker, networking
Published: 2024-02-17 15:27:45

You’ve installed some self hosted services and applications on your Pi but need any easy way to access them on your local LAN and beyond.

This is where NGINX Proxy Manager comes in. When you combine this with PiHole's Local DNS feature it could make your life a whole lot easier.

We're going to:

-   Look at what Nginx Proxy Manager is
-   Install via Portainer or Docker Command Line
-   Create Persistent Mount Folders for our configs
-   Create our Docker Compose File using Nano Text Editor
-   Run and Setup Nginx Proxy Manager using Docker Compose
-   Setup a Custom Hostname for a local service in Nginx Proxy Manager
-   Add this proxy to your existing Pi-Hole Local DNS
-   Forward this Custom Hostname to your IP Address and Port of Choice
-   Test connecting to our local service using just the hostname

___

### What's Nginx Proxy Manager

Nginx Proxy Manager is a GUI web based reverse proxy service that runs on a machine on your network.

It forwards a hostname of your choice and all the HTTP or HTTPS traffic to an IP or Hostname with a port you define e.g. **http://whoogle.this** would take to you to **http://192.168.0.23:5001**

<img width="100%" style="width:100%" src="https://media.giphy.com/media/3orieWOvx0ChPZt1G8/giphy.gif">

You can add and edit entries easily using a GUI web app and even switch these off and on as needed.

There's an also option to automatically get SSLs if you set this up with LetsEncrypt automation but in this guide we'll only be using the forward proxy features.

>
This guide will use PiHole and it's Local DNS Feature so check out this previous guide to get that installed first if you haven't already. [Get Started with Docker : Part 3 Pi Hole](https://reprodev.com/docker-pihole/)

___

We're going to install this using Docker Command Line but you can install this using Portainer instead.

>
If you want to use Portainer than go ahead and check out the guide below and search for it in the App Templates and then skip to "Nginx Proxy Manager Initial Setup"

[Get Started with Docker - Part 4: Portainer : How To Deploy Containers The Easy Way](https://reprodev.com/portainer/)

___

## Where can I install this?

In this guide we're using a Raspberry Pi running Ubuntu Server Minimal.

If you need help with setting that up with Docker on your Raspberry Pi then check out the guide below

[Get Started with Docker - Part 2a: Raspberry Pi Install](https://reprodev.com/raspberry-pi-docker/)

Alternatively, you can run the same commands on WSL using Docker Desktop on a Windows machine if you prefer with the guide below

[Get Started with Docker - Part 2b: Windows 11 Install Guide](https://reprodev.com/windows-docker-desktop-wsl2/)

___

## Set up your persistent Docker Config folders

In this guide and for most of our guides we'll be using the following folder to store all of our config files.

```
/home/$yourusername/docker/Files/AppData/Config
```

It’s best that we start with a folder structure to make it easier to organise and back up the data volumes.

This is the folder structure that we used in the Pi-Hole Docker tutorial but feel free to edit to your own liking.

Once you've started, you can then use this structure for all your Docker config folders. You just need to add the name of the application or service as a new folder at the end.

___

### Create our Nginx Proxy Manager Config folder

First, we're going to create a folder on the Pi to mount to the docker containers you create later as volumes for your NGINX Proxy Manager configs to persist and save.

If you haven't created your config folder then we can do this in a one line command in Linux.

-   SSH into your Docker install

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole01.png)

-   Check you are in the home folder by running **pwd**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole02.png)

-   Copy and paste or type the below line and press **Enter** to create the folder

`mkdir -p Files/AppData/Config/nginx-proxy-manager`

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole03.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole04.png)

-   Change into this the newly created folder

`cd Files/AppData/Config/nginx-proxy-manager`

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole05.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole06.png)

-   You should now be in this new folder **/home/pi/Files/AppData/Config/nginx-proxy-manager**

>
You can use this to store all of it's config files when you spin up or down a container without losing those setting.

Next up, we'll use Nano Text Editor to create our Docker Compose YML File to spin this up.

___

## Creating our Docker Compose file

We're going to use a Docker Compose file for this deployment. Now that we're in the right folder we can create that with the below command

`nano docker-compose.yml`

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole07.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole08.png)

>
If you can't find ****nano**** on your system then run ****sudo apt-get install nano****

-   You can then copy and paste the below code block into the terminal window to create your Docker Compose file. 
-   I'd suggest leaving the Public ports as default but you can change the Admin Web Port if you need to.

```docker
version: "3" services: app: image: 'jc21/nginx-proxy-manager:latest' restart: unless-stopped ports: # These ports are in format <host-port>:<container-port> - '80:80' # Public HTTP Port - '443:443' # Public HTTPS Port - '81:81' # Admin Web Port # Add any other Stream port you want to expose # - '21:21' # FTP # Uncomment the next line if you uncomment anything in the section environment: # Uncomment this if you want to change the location of # the SQLite DB file within the container DB_SQLITE_FILE: "/data/npm.sqlite" # Uncomment this if IPv6 is not enabled on your host DISABLE_IPV6: 'true' volumes: - /home/pi/Files/AppData/Config/nginx-proxy-manager/data:/data - /home/pi/Files/AppData/Config/nginx-proxy-manager/letsencrypt:/etc/letsencrypt
```

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole09.png)

-   Type Ctrl + X to write the file.

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole10.png)

-   Then type Y to save this file.

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole11.png)

-   Press Enter to Exit out back to the command line

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole12.png)

___

## Start up Nginx Proxy Manager

With the **Docker Compose** yml file created we can spin this up using our trusty docker compose command below.

`docker compose up -d`

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole13.png)

-   This will start to download the Nginx Proxy Manager image.

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole14.png)

-   After a few minutes you'll be back at the terminal again.

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole15.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole16.png)

-   Your new Nginx Proxy Manager Container and Docker Network has been started using the folder we created to store it's settings.

We can now log in using a browser into the web gui to set things up.

___

## Let's get started with Nginx Proxy Manager

### Login to Nginx Proxy Manager

-   Open up web browser to go to the Nginx Proxy Manager login page.

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole17.png)

-   We can sign in using the default Admin Credentials on this first login  

> Email address: **[admin@example.com](mailto:admin@example.com)**  
> Password: **changeme**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole18.png)

-   First let’s change that password and the email address to our own. 
-   When you first login if it doesn't open automatically you change these by going to the top right of the Dashboard and clicking **Edit Details**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole19b.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole19.png)

-   Let’s set up the nickname of the Administrator account to **NPMPi4** and click **Save**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole20.png)

-   If you haven't been prompted already then click **Change Password** to set up a more secure password

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole21.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole22.png)

-   Click **Save** and then log out from the top right menu

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole23.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole24.png)

-   Log back into **Nginx Proxy Manager** using the new email address and password you've set to make sure it's working

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole25.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole26.png)

Congratulations, you've now set up an Nginx Proxy Manager instance on your network.

We can to now add this as a proxy on our network using the Local Custom DNS Feature in Pi-hole.

___

## Local DNS on Pi-Hole

If you haven't already set up Pi-Hole then you can follow the below guide to use the same folder structure.

[Get Started with Docker - Part 3: Pi-Hole](https://reprodev.com/docker-pihole/)

If you've already got an existing Pi-Hole set up on your network then you'll need to know the IP of Nginx Proxy Manager if it isn't running on the same machine.

We'll be using the Pi-Hole as to forward specific requests with the domain ****.this****

We can forward the address **whoogle.this** to our Whoogle instance for any devices using our Pi-Hole for their DNS.

___

## Setting up Local Custom DNS Records on Pi-hole

-   Start by logging into your **Pi-Hole** and scroll down to the **Local DNS** section on the left hand menu
-   Click **DNS Records**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole27.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole28.png)

-   Enter the details for your **A Record** with Domain and IP Address

>
In our example these are, Domain ****proxy.this**** and the IP Address of ****Nginx Proxy Manager (192.168.0.23)****

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole29.png)

-   Make sure you click **Add** to save this to the current **Custom DNS** list

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole30.png)

-   If we try to go to **http://proxy.this** now before joining the **Pi-hole DNS** we'll get the below result in Google or an existing website on the internet

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole31.png)

-   This is a Windows 11 machine currently not connected to the Pi-hole and using our ISP DNS from our router.
-   We'll go ahead and manually change the DNS to use the Pi-hole in Network Settings under the IPv4 Settings in Windows 11
-   Add our Pi-hole address as the Preferred DNS under the IPv4 settings
-   Click Save once you've added our Pi-hole IP Address

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole32.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole33.png)

-   If you now go to **proxy.this** in your browser, you'll see the Nginx Proxy Manager default welcome page

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole34.png)

-   We can now use http://proxy.this:81 to get to Nginx Proxy Manager to test and add our first forwarded service, Whoogle.

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole35.png)

___

## Add a Proxy Host in Nginx Proxy Manager

The major advantage in using this setup is that you can set Proxy Hosts to define the IP address and port number when you use the reverse proxies.

Let's go ahead and add our first Proxy Host in Nginx Proxy Manager.

-   Login using your email address and password from earlier

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole36.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole37.png)

Once logged in you will currently have 0 Proxy Hosts set up

-   Open up another tab in your browser and let's go to our Whoogle instance

>
Remember this could be anywhere on your local network but in our example it's on the same machine on the same IP address

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole38.png)

-   Make a note of this IP and Port number, if you haven't already and go back to your Nginx Proxy Manager tab
-   Click the **Proxy Hosts** button and then **Add Proxy Host**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole39.png)

-   Go ahead and add **whoogle.this** to **Domain Names**

>
Press ****Enter**** or click ****Add whoogle.this...**** to make sure this is added to the ****Domain Names**** for the ****New Proxy Host****

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole40.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole41.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole42.png)

-   Add the Forward IP address for your W**hoogle** instance and the Forward port number

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole43.png)

-   Toggle the below options and click the **Save** button

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole44.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole45.png)

-   This should now be added to your list of Proxy Hosts in Nginx Proxy Manager

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole46.png)

We now need to go and add this as a CNAME record in Pi-hole

___

## Adding CNAME Record in Pi-hole

Nginx Proxy Manager will handle the IP Address and Port number for us but we'll still use the Pi-hole Local DNS to forward the .this domain locally.

Before the **Pi-hole DNS** knows how to forward **whoogle.this** address to Nginx Proxy Manager and in turn our **Whoogle** instance for us, we need to add a **CNAME** record in Pi-hole.

-   Log back into the **Pi-hole** in a new tab in your browser if you haven't got it open already

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole47.png)

-   On the left hand menu, under **Local DNS** click the **CNAME Records** option
-   You will now be on the Local CNAME Records page
-   Add the service and hostname you want to forward on the left in **Domain** \- **whoogle.this**
-   Add the address of Nginx Proxy Manager on the right in the **Target Domain** - **proxy.this**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole48.png)

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole49.png)

-   Click **Add** to add this to the **List of local CNAME records**
-   You'll get a notification at the top right to let you know this has been added

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole50.png)

-   Scroll down to check it's in the list current list on the **Pi-hole**

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole51.png)

___

## Testing the Forward Proxy

We can now test this new forward proxy on our Pi-hole DNS connected device

-   Open up another tab in your browser and your new proxy hostname
-   If you're following along with the same subdomain then head to http://whoogle.this

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole52.png)

-   We can run a quick search just to make sure that everything is working in our **Whoogle** instance using this address

![](https://reprodev.com/content/images/2024/02/08nginxpm-pihole53.png)

Congratulations, you’ve set up your first forward on your local DNS. You can now add other services and use them instead of having to remember all those IP addresses.

This is also useful if those IP addresses ever change, as you can just change it in Nginx Proxy Manager and not have to change the hostname in any references in your overall network.

Remember, these hostnames won't work when you aren't connected to your Pi-hole DNS but this can be setup to be used securely and remotely.

I'll outline how this can be done in a future guide as it's a very useful feature when when you're not on your local network using Tailscale VPN.

___

For more Docker Compose files check out **ReproDev Recipes** on GitHub with Docker Compose files for you to try out yourself

[GitHub - reprodev/reprodev-recipes: ReproDev Recipes is a repository of code snippets and docker compose files from reprodev.com](https://github.com/reprodev/reprodev-recipes/tree/main?ref=reprodev.com)

___

Check out the guide below if you want more information on What Docker is and how to get started

[Looking to get started with Docker? Learn about Docker Compose Files, Docker Images, Docker Engine and Docker Desktop in this guide to containers](https://reprodev.com/get-started-with-docker-intro-to-docker/)

___

Don't forget to explore the rest of our website as we build out more content. Stay tuned for more tutorials, tips, and tricks to help you make tech work for you.

If you want to stay up-to-date with regular updates, make sure to subscribe to our free mailing list.

___