Docker

Get Started with Docker - Part 5: Forward Custom Hostnames with Nginx Proxy Manager and Pi-Hole

Repro Dev

Feb 17, 2024 • 14 min read

Logos Property of jc21.com & Docker https://www.docker.com

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

via GIPHY

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.

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"

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

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

Easily install Docker Desktop & WSL 2 on Windows 11 with our step-by-step guide. Start using Docker containers on Windows in no time at all

ReproDevRepro Dev

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

Check you are in the home folder by running pwd

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

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

Change into this the newly created folder

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

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

💡

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.

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

Type Ctrl + X to write the file.

Then type Y to save this file.

Press Enter to Exit out back to the command line

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

This will start to download the Nginx Proxy Manager image.

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

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

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

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

Email address: [email protected]
Password: changeme

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

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

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

Click Save and then log out from the top right menu

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

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.

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

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)

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

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

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

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

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

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.

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

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

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

Add the Forward IP address for your Whoogle instance and the Forward port number

Toggle the below options and click the Save button

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

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

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

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

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

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

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

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

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

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.