Goal
A Tutorial Repo for migrating your Nginx Proxy Manager proxy setup to Nginx. I wrote this originally for this reddit post and to post this my Github profile. Thought my website would also be a good place to share it for any passers-by.
To give clear instructions to help users migrate from using Nginx Proxy Manager (NPM) to standard Nginx. This tutorial is not exhaustive and there are many other implementations of this transition. I would recommend checking out the many Nginx Documentation Sites and tutorials to learn more.
Introduction
If you’re anything like me and you got into the self-hosted/homelab/diy game sometime within the last 5 years, you’ve likely been recommended to use Nginx Proxy Manager as one of the choice Reverse Proxy services. If you’ve also been paying attention to various self-hosted communities, you may have also come across Christian Lempa’s Video on trusting smaller self hosted projects and tools.
Spoilers: He roasts NPM in his video and towards the end says he won’t be using NPM anymore. He also, perhaps purposely, doesn’t share which tool he will be migrating to.
Whether you follow Christian away from NPM or not, it dawned on me that while NPM is using a very trusted web server and reverse proxy under the hood, I hadn’t taken the time to understand how an Nginx Config actually worked. Since NPM was already creating most of the files for Nginx, I got to reading through all the files and reworking them so that I could begin using Nginx without the NPM gui.
Contributing: This is not all encompassing of Nginx possibilities. Including instructions for various installation methods, using OpenResty, and any other migrations or use cases would help the community. If you’d like to add in additional information on how to migrate from NPM to Nginx, that is welcome. Simply submit a PR with your steps.
TL;DR - Quick Steps
-
Copy the following contents (including sub-directories) from the NPM
/data/nginx
directory to the Nginx/etc/nginx
folder:proxy_hosts
>sites-available
conf.d
>conf.d
snippets
>snippets
custom_ssl
>custom_ssl
(if applicable)
-
Edit each file in your
sites-available
directory and update the paths. Most will change from/data/nginx/
to/etc/nginx
. -
Edit your
nginx.conf
file and ensure the following two paths are there:include /etc/nginx/conf.d/*.conf;
andinclude /etc/nginx/sites-enabled/*;
-
Symlink the proxy host files in
sites-available
tosites-enabled
ln -s * ./sites-enabled
-
Test your changes with
nginx -t
. Make appropriate changes if there are error messages.
Pre-requisites & Assumptions
I am using an Ubuntu VM with NPM and it’s db as a Docker Container while Nginx is installed natively on the machine. You don’t have to use this setup exactly, but I am making a few assumptions as to what you should have access to before you begin. I am also using custom SSL certs, but theoretically, the transition should be the same when using Lets Encrypt.
I’ve added some example files to show before and after changes to this repo and outlined file trees below.
- You understand the basics of what a Reverse Proxy is doing and are sticking with some stock settings (like exposing port 80 an 443).
- You’ve installed NPM and Nginx using your preferred method.
- You have access to both NPMs file tree and Nginx’s.
- If using NPM in docker, make sure you’ve mapped a local volume on the host to the container.
- My setup using docker-compose is the following:
/user/nginx/data:/data
. - Know where your Nginx files are. If using docker, same as above, make sure your container directories are mapped to the host.
- For a linux install, they should be accessible at
/etc/nginx
. - You know how to edit files at the command line using
nano
,vi
,vim
,neovim
,emacs
, or something else.
Nginx Files
Nginx uses the nginx.conf
file and within that file, it will include your proxy files. These exist under ./nginx/sites-enabled/
. In the main nginx.conf
file, the line include /etc/nginx/sites-enabled/*;
will bring in those files to the config file, making the proxies accessible.
How to Transition - Detailed Version
-
Since NPM uses Nginx under the hood, they are both, by default, going to try and use ports 80 and 443 to serve up your apps and content. Turn off both systems.
- Docker:
docker stop [app_container, db_container]
- Systemd:
systemctl stop nginx
- Docker:
-
Copy your
proxy_host
(NPM) files to thesites-available
(Nginx) folder.cp -r /user/nginx/data/nginx/proxy_hosts/* /etc/nginx/sites-available/
-
Nginx doesn’t really care what the files are called, but NPM numbers them based on the order in which you added them in the GUI. I find it better to rename them to what service they actually serve up for easier identification later.
-
Copy your
custom_ssl
folder from NPM to thecustom_ssl
folder in Nginx. See the following step for the various default paths in both systems.cp -r /user/nginx/data/custom_ssl/* /etc/nginx/custom_ssl/
-
Copy the
conf.d
folder from NPM to theconf.d
folder in Nginx. Note: For some reason, not all of the files in the proxy files were actually in myconf.d
directory. If you’re missing any files, please download and/or copy and paste them from the NPM Repocp -r /user/nginx/data/nginx/conf.d /etc/nginx/
-
If you had any additional files included in the Advanced section of an NPM Proxy Host, make sure you copy them over. For my setup and this tutorial, they were all located in the
snippets
directory.cp -r /user/nginx/data/nginx/snippets/* /etc/nginx/snippets/
-
There are a number of lines that need to be updated in each proxy configuration file to make them work with Nginx. I’ve placed additional comments in
./proxy_host/npm_proxy.conf
file. The line changes are the following:-
Custom SSL path:
- NPM path:
/data/custom_ssl...
- Nginx path:
/etc/nginx/custom_ssl...
- NPM path:
-
conf.d:
- The paths should remain the same. However, if you changed the path for
conf.d
in Nginx and differed in step 5, above, make sure you use the correct path.
- The paths should remain the same. However, if you changed the path for
-
Access & Error Logs
- NPM path:
/data/logs/...
- Nginx path:
/var/log/nginx/...
- NPM path:
-
-
Double Check all your paths! If this is your first time using Nginx, make sure every directory is correct! Save your work.
-
Navigate to the
nginx.conf
file which is located at/etc/nginx/
. You can see the one I am using in this repo. -
Make sure that you have the following two lines in the main conf file and that they are pointing to the appropriate directories in the nginx directory path.
include /etc/nginx/conf.d/*.conf;
andinclude /etc/nginx/sites-enabled/*;
-
You’ll notice that you ensured there was a
sites-enabled
directory in the configuration file, but you changed all your proxy host config files insites-available
! Good eye, all that’s left is to symlink the files tosites-enabled
so that nginx can start using them. -
To symlink the available proxy files run the following command within the
sites-available
directory:ln -s * ./sites-enabled
-
Once you’re confident that you’ve done all the above correctly, you can test your setup using nginx command and flags. While in the directory with your
nginx.conf
file - usually/etc/nginx
- run the following command:nginx -t
. -
If all is working as expected you should see the below output. If it returns any errors, fix them appropriately. It will usually tell you what line is throwing the error. In this case, there’s a high likelihood that it will be path error.
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
And that’s it! You can now restart your nginx service on the host and access all your sites just as if you were using Nginx Proxy Manager! Make sure you take a look at your logs and system’s status should nginx fail to start.
Additional Information/Appendix
File Trees for NPM (in container) and Nginx (on host)
I did not expand every directory in these trees. Only the ones that are pertinent for reference in this tutorial.
NGINX
βββ conf.d
βΒ Β βββ include
βΒ Β βββ assets.conf
βΒ Β βββ block-exploits.conf
βΒ Β βββ force-ssl.conf
βΒ Β βββ ip_ranges.conf
βΒ Β βββ proxy.conf
βΒ Β βββ resolvers.conf
βββ custom_ssl
βΒ Β βββ npm-1
βΒ Β βΒ Β βββ fullchain.pem
βΒ Β βΒ Β βββ privkey.pem
βΒ Β βββ npm-2
βΒ Β βΒ Β βββ fullchain.pem
βΒ Β βΒ Β βββ privkey.pem
βΒ Β βββ npm-3
βΒ Β βββ fullchain.pem
βΒ Β βββ privkey.pem
βββ fastcgi.conf
βββ fastcgi_params
βββ koi-utf
βββ koi-win
βββ mime.types
βββ modules-available
βββ modules-enabled
βββ nginx.conf
βββ proxy_params
βββ scgi_params
βββ sites-available
βΒ Β βββ auth.conf
βΒ Β βββ bitwarden.conf
βΒ Β βββ codehub.conf
βΒ Β βββ default.backup
βΒ Β βββ files.conf
βΒ Β βββ notes.conf
βΒ Β βββ photos.conf
βΒ Β βββ rsmsn-root.conf
βΒ Β βββ wordle.conf
βΒ Β βββ wordle-it.conf
βββ sites-enabled
βΒ Β βββ auth.conf -> /etc/nginx/sites-available/auth.conf
βΒ Β βββ bitwarden.conf -> /etc/nginx/sites-available/bitwarden.conf
βΒ Β βββ codehub.conf -> /etc/nginx/sites-available/codehub.conf
βΒ Β βββ files.conf -> /etc/nginx/sites-available/files.conf
βΒ Β βββ notes.conf -> /etc/nginx/sites-available/notes.conf
βΒ Β βββ photos.conf -> /etc/nginx/sites-available/photos.conf
βΒ Β βββ wordle.conf -> /etc/nginx/sites-available/wordle.conf
βΒ Β βββ wordle-it.conf -> /etc/nginx/sites-available/wordle-it.conf
βββ snippets
βΒ Β βββ authelia-authrequest-basic.conf
βΒ Β βββ authelia-authrequest.conf
βΒ Β βββ authelia-authrequest-detect.conf
βΒ Β βββ authelia-location-basic.conf
βΒ Β βββ authelia-location.conf
βΒ Β βββ authelia-location-detect.conf
βΒ Β βββ fastcgi-php.conf
βΒ Β βββ proxy.conf
βΒ Β βββ snakeoil.conf
βββ uwsgi_params
βββ win-utf
NPM
βββ data
βΒ Β βββ access
βΒ Β βββ custom_ssl
βΒ Β βΒ Β βββ npm-1
βΒ Β βΒ Β βΒ Β βββ fullchain.pem
βΒ Β βΒ Β βΒ Β βββ privkey.pem
βΒ Β βΒ Β βββ npm-2
βΒ Β βΒ Β βΒ Β βββ fullchain.pem
βΒ Β βΒ Β βΒ Β βββ privkey.pem
βΒ Β βΒ Β βββ npm-3
βΒ Β βΒ Β βββ fullchain.pem
βΒ Β βΒ Β βββ privkey.pem
βΒ Β βββ keys.json
βΒ Β βββ letsencrypt-acme-challenge
βΒ Β βββ logs
βΒ Β βββ mysql
βΒ Β βββ nginx
βΒ Β βββ custom
βΒ Β βββ dead_host
βΒ Β βββ default_host
βΒ Β βββ default_www
βΒ Β βββ dummycert.pem
βΒ Β βββ dummykey.pem
βΒ Β βββ proxy_host
βΒ Β βΒ Β βββ 10.conf
βΒ Β βΒ Β βββ 11.conf
βΒ Β βΒ Β βββ 12.conf
βΒ Β βΒ Β βββ 13.conf
βΒ Β βΒ Β βββ 15.conf
βΒ Β βΒ Β βββ 1.conf
βΒ Β βΒ Β βββ 2.conf
βΒ Β βΒ Β βββ 4.conf
βΒ Β βΒ Β βββ 5.conf
βΒ Β βΒ Β βββ 6.conf
βΒ Β βββ redirection_host
βΒ Β βββ snippets
βΒ Β βΒ Β βββ authelia-authrequest-basic.conf
βΒ Β βΒ Β βββ authelia-authrequest.conf
βΒ Β βΒ Β βββ authelia-authrequest-detect.conf
βΒ Β βΒ Β βββ authelia-location-basic.conf
βΒ Β βΒ Β βββ authelia-location.conf
βΒ Β βΒ Β βββ authelia-location-detect.conf
βΒ Β βΒ Β βββ proxy.conf
βΒ Β βββ stream
βΒ Β βββ temp
βββ docker-compose.yml
βββ letsencrypt
βββ renewal-hooks