How to Migrate from an Existing NGINX Proxy Manager Deployment and Keep Configuration

To migrate from an existing NGINX Proxy Manager installation to a version which provides also open-appsec integration here's some guidance:

This is only relevant if you want to keep your existing NGINX Proxy Manager configuration, otherwise we suggest to start fresh with the deployment instructions further above on this page.

Note that the specific steps can vary based on customizations that you might have done to the original NGINX Proxy Manager's docker compose file.

The below is assuming you did a deployment by using the default docker-compose.yml file as shown here: https://nginxproxymanager.com/setup/#running-the-app .

• Change into your existing folder that contains the docker-compose.yml file and all related files and folders for your current NGINX Proxy Manager deployment.

• Stop your current deployment with docker compose down in the folder that contains your docker-compose.yaml file used for the NGINX Proxy Manager deployment

• Make a full backup of your existing folder that contains the NGINX Proxy Manager docker compose environment, including any mounted volumes like ./data and ./letsencrypt, etc. to a safe location. This will allow you to bring it up with docker-compose up later exactly as it was before the migration, if required for some reason.

• Rename the original docker-compose.yml to docker-compose.orig.yaml.

open-appsec managed from NPM WebUI

• Within the directory which you want to use for the deployment: Create a folder appsec-localconfig which will hold the appsec declarative configuration file (this will be managed by the enhanced NPM WebUI).

  mkdir ./appsec-localconfig

• Download the initial declarative configuration file for open-appsec into that folder:

  wget https://raw.githubusercontent.com/openappsec/open-appsec-npm/main/deployment/local_policy.yaml -O ./appsec-localconfig/local_policy.yaml

• Create the new docker-compose.yaml file for the open-appsec NGINX Proxy Manager integration:

  wget https://raw.githubusercontent.com/openappsec/open-appsec-npm/main/deployment/docker-compose.yaml

• Edit the docker-compose.yaml file and replace "[e-mail]" with your own email address, so we can provide assistance in case of any issues with the specific deployment in the future and provide information proactively regarding open-appsec.

  This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future

• If you did any special changes to the original docker-compose.yml file now is the time to apply these also to the docker-compose.yaml file for the open-appsec NPM integration you just downloaded/created in step 3 of the deployment instructions. For this compare the new docker-compose.yaml with the renamed docker-compose.orig.yaml file.

• Below find the relevant folders typically containing the persistent configuration of NGINX Proxy (NPM) Manager, they will also be mounted as part of the open-appsec NPM integration docker-compose.yaml so that all your existing configuration should be kept. Only if for some reason you changed the local folder locations for these specific docker volume mounts in the past, please make sure to adjust those as well in the new docker-compose.yaml file for the open-appsec NGINX Proxy Manager integration.

    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

Your existing NGINX Proxy Manager (and Let's Encrypt) configuration will still be available also once migrated to the open-appsec enhanced NGINX Proxy Manager deployment as long as it still resides in the local ./data and ./letssencrypt folders (see relevant excerpt from the docker-compose.yaml file below).

• Run docker-compose up to start the deployment of all relevant containers:

  docker-compose up -d

• Check if the appsec-npm and the appsec-agent containers are up and running:

  docker ps

• Now you can login with your web browser to the WebUI of the NGINX Proxy Manager (NPM) with open-appsec integration as follows: (Note that as you kept your existing NPM configuration your existing user credentials for the login should also still work.)

http://[hostname or IP of your host]:81

After switching to and loading the new Nginx Proxy Manager (NPM) pages, we recommend clearing your browser’s cache and cookies to ensure the updated configuration is applied correctly.

open-appsec managed from central WebUI

Prerequisites

• Access to a SaaS tenant on my.openappsec.io (WebUI for SaaS management) Follow the instructions available here:

Sign-Up and Login to Portal

• Agent profile created for open-appsec Docker deployment in SaaS tenant Follow the instructions available here. Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below:

Create a Profile

Instructions

• Create the new docker-compose.yaml file for the open-appsec NGINX Proxy Manager integration:

  wget https://raw.githubusercontent.com/openappsec/open-appsec-npm/main/deployment/managed-from-open-appsec-ui/docker-compose.yaml

• Edit the docker-compose.yaml with the Token from the Prerequisites.

• If you did any special changes to the original docker-compose.yml file now is the time to apply these also to the docker-compose.yaml file for the open-appsec NPM integration you just downloaded/created in step 3 of the deployment instructions. For this compare the new docker-compose.yaml with the renamed docker-compose.orig.yaml file.

• Below find the relevant folders typically containing the persistent configuration of NGINX Proxy (NPM) Manager, they will also be mounted as part of the open-appsec NPM integration docker-compose.yaml so that all your existing configuration should be kept. Only if for some reason you changed the local folder locations for these specific docker volume mounts in the past, please make sure to adjust those as well in the new docker-compose.yaml file for the open-appsec NGINX Proxy Manager integration.

    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

Your existing NGINX Proxy Manager (and Let's Encrypt) configuration will still be available also once migrated to the open-appsec enhanced NGINX Proxy Manager deployment as long as it still resides in the local ./data and ./letssencrypt folders (see relevant excerpt from the docker-compose.yaml file below).

• Run docker-compose up to start the deployment of all relevant containers:

  docker-compose up -d

• Check if the appsec-npm and the appsec-agent containers are up and running:

  docker ps

• Now you can login with your web browser to the WebUI of the NGINX Proxy Manager (NPM) with open-appsec integration as follows: (Note that as you kept your existing NPM configuration your existing user credentials for the login should also still work.)

http://[hostname or IP of your host]:81

After switching to and loading the new Nginx Proxy Manager (NPM) pages, we recommend clearing your browser’s cache and cookies to ensure the updated configuration is applied correctly.

Congratulations, you successfully migrated your existing NGINX Proxy Manager deployment to the NGINX Proxy Manager integrated with open-appsec.