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

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

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


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
You’ve set up Docker on your operating system and device of choice. You’re ready to start spinning up containers and seeing what Docker is all about. In this guide, we’ll spin up one of the most useful services in a container and a great introduction to the Docker ecosystem. We’ll

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
If you’ve been following along so far then you’ve already managed to get Docker installed on your system and your first Docker container service deployed. A lot of Docker management can be done through the command line and a lot of people like working with docker compose files and docker

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
Easily install Docker & Docker Compose on a Raspberry Pi 4 with our step-by-step guide. Start using Docker containers on your Pi in no time at all

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

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.


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"
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
      # 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
      # 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'
      - /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

Login to 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.

Get Started with Docker - Part 3: Pi-Hole
You’ve set up Docker on your operating system and device of choice. You’re ready to start spinning up containers and seeing what Docker is all about. In this guide, we’ll spin up one of the most useful services in a container and a great introduction to the Docker ecosystem. We’ll

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 (
  • 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.

  • Login using your email address and password from earlier

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

GitHub - reprodev/reprodev-recipes: ReproDev Recipes is a repository of code snippets and docker compose files from
ReproDev Recipes is a repository of code snippets and docker compose files from - GitHub - reprodev/reprodev-recipes: ReproDev Recipes is a repository of code snippets and docker compo…

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

Get Started with Docker - Part 1 : An Intro to Docker
Looking to get started with Docker? Learn about Docker Compose Files, Docker Images, Docker Engine and Docker Desktop in this guide to containers

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.