Deploy NGINX Proxy Manager with open-appsec managed from NPM WebUI

Deployment:

Before you start, make sure to have a Linux environment with Docker and Docker Compose available.

If you want to migrate from an existing NGINX Proxy Manager deployment to use this integration with open-appsec, please check out our guide which is available here: How to Migrate from an Existing NGINX Proxy Manager Deployment and Keep Configuration

To deploy NGINX Proxy Manager with open-appsec integration follow the steps below

Prerequisites

Linux Docker Host with root permission
Docker-Compose tool installed
(Optional, Recommended) Sign-Up and Login to WebUI Portal If you want to locally manage your open-appsec WAF deployment using the NPM WebUI but still connect to central WebUI for viewing the local configuration (in read-only), central monitoring, logging and reporting: Follow the instructions below to sign-up and login to the WebUI available at https://my.openappsec.io:

Sign-Up and Login to Portal

(Optional, Recommended) Create deployment profile for the open-appsec deployment in WebUI Portal If you signed-up and logged in to the WebUI Portal (see prerequisite above), now follow the instructions below to create a new deployment profile for your open-appsec deployment. 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

Deployment

To deploy NGINX Proxy Manager integrated with open-appsec using `docker-compose` (and optionally connect also to the central open-appsec WebUI) follow the steps below:

Create a folder for your new open-appsec deployment and switch to that folder, e.g.

mkdir open-appsec-deployment
cd ./open-appsec-deployment

Download the docker compose file for your desired open-appsec integration

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager/docker-compose.yaml

docker-compose.yaml file content:

https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager/docker-compose.yamlraw.githubusercontent.com

Download the .env file for your desired open-appsec integration and adjust the configuration to your requirements as described below:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager/.env

.env file content:

https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-proxy-manager/.envraw.githubusercontent.com

If you created a deployment profile in the WebUI and copied the Token from it:
Edit the .env file and add your token to the key APPSEC_AGENT_TOKEN.
If you did not create a deployment profile in the WebUI and do not want to connect your deployment to central WebUI (SaaS) at all:
Set the value standalone for the key COMPOSE_PROFILES which will activate the deployment of additional containers which are required only when not connected to the open-appsec central WebUI at all (resulting in standalone, locally, declaratively managed deployment).
Replace [email protected] in the .env file with your own email. (More details below.)

Available settings in the `.env` file allowing further customization of the deployment:

APPSEC_AGENT_TOKEN: For connecting your open-appsec deployment to central WebUI set APPSEC_AGENT_TOKEN to your own deployment profile token as copied from profile settings in the open-appsec central WebUI (see section Prerequisites above).

COMPOSE_PROFILES: Possible values you can set for this key: (you can set multiple values, separated by comma)

standalone : This will activate the deployment of additional containers which are required only when you are not connected to the open-appsec central WebUI at all, resulting in standalone, locally, declaratively managed deployment.

Only activate the standalone profile in case you did not set a WebUI deployment profile token as value for the APPSEC_AGENT_TOKEN key (see above)!

The additional containers which get deployed in standalone mode introduce some additional functionality, which is relevant for standalone deployments only (that same functionality is already available when connected to open-appsec's central management WebUI): - Local syncing of learning between open-appsec processes and agents - View learning progress on CLI with open-appsec-tuning-tool - Receive configuration recommendations based on the learning progress using the open-appsec-tuning-tool - Receive tuning suggestions and manage them (approve/reject) using the open-appsec-tuning-tool More details on the open-appsec-tuning-tool here: Track Learning and Local Tuning in Standalone Deployments

juiceshop : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. In the .env file you also find a download link for the proxy-specific configuration allowing you to access the juiceshop backend via the proxy. More info on the OWASP juiceshop project: https://owasp.org/www-project-juice-shop/

Do not activate the juiceshop profile in production environments as the juiceshop container is intentionally highly vulnerable and meant for testing in lab environments only!

USER_EMAIL: (Optional) Associate your email address with your specific deployment by replacing [email protected] with your own email address.

This allows the open-appsec team to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. 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.

APPSEC_HTTPS_PROXY: (Optional) Configure an HTTP(S) proxy server to be used by the agent.

APPSEC_AUTO_POLICY_LOAD: (Optional) When set to true, allows you to set the open-appsec agent to automatically apply any new changes in the local_policy.yaml file without having to restart the agent container or applying the changes with open-appsec-ctl -ap (note that this can take up to 30 seconds). This is useful especially in DevOps scenarios with continuous deployment scenarios.

APPSEC_VERSION: Allows you to specify a specific version for deployment instead of using the default latest version for the containers provided by open-appsec (not relevant for postgres container).

Additional configuration available specifically for this integration type:

NPM_DATA: Specify the local folder on the host for the volume mount of the NPM data directory, in the appsec-nginx-proxy-manager container this gets mounted into /data.

NPM_LETSENCRYPT: Specify the local folder on the host for the LetsEncrypt data, in the appsec-nginx-proxy-manager container this gets mounted into /etc/letsencrypt.

For testing purposes in a lab environment you can activate the deployment of the vulnerable juiceshop-backend container via COMPOSE_PROFILES key (see above) and then deploy the available configuration example for exposing it via the proxy, which is provided by the open-appsec team (download link is provided in the .env file).

You find some additional advanced configuration options described within the docker-compose.yaml file as comments.

Download the initial declarative configuration file for open-appsec into new subfolder ./appsec-localconfig (note this is a specifically adjusted version for the NPM integration):

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

This example configuration file is already set to mode: prevent-learn so that open-appsec will prevent attacks right from the start. Here's the path for an alternative local-config.yaml file set to detect-learn mode. https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/detect/local_policy.yaml (or simply adjust the setting in the mode setting in the earlier local_policy.yaml file to detect-learn) In production environments it's always recommended to start in detect-learn mode to allow open-appsec to achieve a certain learning level based on traffic observed before moving to prevent-learnfor better detection accuracy and strongly reduced false positives. Read more about this here: Track Learning and Move From Learn/Detect to Prevent

Perform the deployment

docker-compose up -d

You will see output similar to the below. (The example screenshot below is for an NGINX deployment.) Note that the amount of container will vary based between deployments with and without connection to central WebUI.

Verify that all containers are up and running by verifying their status in docker ps output. Note that the amount of container will vary based between deployments with and without connection to central WebUI.

docker ps

You will see output similar to the below: (The example screenshot below is for an NGINX deployment.)

This version of the docker-compose for NGINX Proxy Manager integration with open-appsec is now deprecated since 2025-08-25, please use the "recommended" version instead which contains many improvements.

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/managed-from-npm-ui/local_policy.yaml -O ./appsec-localconfig/local_policy.yaml

Create a docker-compose.yaml file with the content below, it can be downloaded as follows:

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

docker-compose.yaml content:

version: '3.3'
# docker compose for nginx proxy manager open-appsec integration
# open-appsec managed and monitored from nginx proxy manager web ui

services:
  appsec-npm:
    container_name: npm-attachment
    image: 'ghcr.io/openappsec/nginx-proxy-manager-attachment:latest'
    ipc: host
    restart: unless-stopped
    ports:
      - '80:80' # Public HTTP Port
      - '443:443' # Public HTTPS Port
      - '81:81' # Admin Web Port
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
      - ./appsec-logs:/ext/appsec-logs
      - ./appsec-localconfig:/ext/appsec

  appsec-agent:
    container_name: appsec-agent
    image: 'ghcr.io/openappsec/agent:latest'
    network_mode: service:appsec-npm
    ipc: host
    restart: unless-stopped
    environment:
      # adjust with your own email below
      - [email protected]
      - nginxproxymanager=true
      - autoPolicyLoad=true
    volumes:
      - ./appsec-config:/etc/cp/conf
      - ./appsec-data:/etc/cp/data
      - ./appsec-logs:/var/log/nano_agent
      - ./appsec-localconfig:/ext/appsec
    command: /cp-nano-agent --standalone

Edit the docker-compose.yaml file and replace "[email protected]" 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
Start the deployment of all relevant containers using docker-compose:

docker-compose up -d

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

docker ps

Congratulations, you successfully deployed NGINX Proxy Manager with open-appsec integration!

For Production usage we recommend to switch from using the Basic to the more accurate Advanced Machine Learning model, as described here:

Using the Advanced Machine Learning Model

Now you can login with your web browser to the WebUI of NGINX Proxy Manager with open-appsec integration as follows:

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

At first login please use the following default administrator user credentials: E-mail address: [email protected] Password: changeme

You will then be prompted to provide your own user details and asked to change the password, before being presented with the NGINX Proxy Manager Dashboard view:

Configuration

To learn how to use NGINX Proxy Manager (NPM) see project documentation: https://nginxproxymanager.com (NPM usage and configuration will not be explained here).

Once you created a new Proxy Host within NGINX Proxy Manager WebUI you can now easily enable and configure open-appsec protection (see also screenshot below):

Enable open-appsec by flipping the “open-appsec” switch to enabled.
Select the Enforcement Mode, it can be either “Prevent-Learn” or “Detect-Learn”
Select the minimum confidence level for open-appsec to prevent an attack (only relevant when in prevent mode), it can be either “Critical”, “High” or “Medium” confidence.
Click “Save”

This screenshot as an example shows a “Proxy Host” reverse proxy configuration in NPM that will listen to inbound traffic for hostnames “100.25.161.101”, “localhost” or “my.webserver.com”.

This Proxy Host has open-appsec enabled in “Prevent-Learn” mode and therefore will prevent incoming http or https requests when there’s a minimum confidence level of “High” or higher, as configured for the “Minimum confidence for prevent” setting.

Non-malicious traffic will then be proxied using “http” protocol to the configured backend webserver with the IP address “192.168.160.2” on port “80”.

If you deployed the new docker-compose file (beta) which includes the optional vulnerable juiceshop container (just for testing purposes, do not use in production environments!) and added the value juiceshop to the parameter COMPOSE_PROFILES then you can configure juiceshop-backend in the Forward Hostname / IP field of the Edit Proxy Host window to proxy inbound traffic to it.

Using Custom Locations in Proxy Host objects

If you are using “Custom locations” in NPM for a more granular backend configuration you can configure open-appsec in similar same way as described above, but configuration will then be specific and applied only to this “Custom location”:

This gives you for example the flexibility to set open-appsec to “Detect-Learn” for a specific “Custom location” while the main Proxy Host configuration is set to “Prevent-Learn”. Alternatively, you could also use this option to have open-appsec configured to “Detect-Learn” for your Proxy Host configuration but already set it to “Prevent-Learn” for some specific paths which require immediate protection or which you want to test prevent mode before enabling it for the “whole” Proxy Host.

Changes in the open-appsec configuration performed and saved in the NPM Web UI can take up to 30 seconds before they become effective.

How to view open-appsec Logs in NPM Web UI:

If you want to check out the open-appsec Logs click on the new menu option “Security Log” which allows you to view the open-appsec specific logs directly from the NPM Web UI. Within the Security Log view you can chose between three separate views:

Important Events
All Events
Notifications

The "open" button at the beginning of each log allows you to view the full log in json format:

How to configure open-appsec advanced settings:

Performing direct changes of the local declarative configuration file for open-appsec in the "open-appsec Advanced" section will be "at your own risk", as you might break the configuration. Only do this if required and if you know what you do or test stuff in a risk-free lab environment.

Note that as the integration with NPM Web UI is built based on the v1beta1 local configuration schema of open-appsec, you must only use the v1beta1 version of open-appsec with this integration.

If you have requirement to manage open-appsec WAF declaratively with local configuration in v1beta2 schema version, you can instead use the container image nginx-proxy-manager-centrally-managed which does not contain the integration with NPM Web UI but just the open-appsec attachment, this is compatible with both, v1beta1 and v1beta2 schema versions.

What if you want to configure some advanced settings of open-appsec which are not covered or not covered “yet” as part of the open-appsec enhanced NPM WebUI? We thought about this as well and added an extra editor allowing you to adjust the declarative open-appsec configuration under “Settings” -> “open-appsec Advanced”.

The local policy file specification for v1beta1 configuration schema is available here: Local Policy File (Advanced)

Make sure to push the “save” button once you did any changes here and be especially careful with the configuration that has “npm-managed...” as part of the name, as these configuration elements are created and partly managed by the open-appsec configuration in the NPM WebUI. As a rule of thumb only adjust stuff for which there’s no UI element yet to configure it and be aware that e.g. disabling open-appsec in a “Proxy Host” or “Custom Location” might also remove the corresponding configuration from the open-appsec Configuration File.

Check out the open-appsec documentation if you want to learn more about all the additional options and security layers which are available in open-appsec: docs.openappsec.io

PreviousNGINX Proxy Manager NextDeploy NGINX Proxy Manager with open-appsec managed from central WebUI (SaaS)

Last updated 29 days ago

Was this helpful?

Deployment:

To deploy NGINX Proxy Manager with open-appsec integration follow the steps below

Prerequisites

Deployment

To deploy NGINX Proxy Manager integrated with open-appsec using docker-compose (and optionally connect also to the central open-appsec WebUI) follow the steps below:

Available settings in the .env file allowing further customization of the deployment:

Congratulations, you successfully deployed NGINX Proxy Manager with open-appsec integration!

Configuration

Using Custom Locations in Proxy Host objects

How to view open-appsec Logs in NPM Web UI:

How to configure open-appsec advanced settings:

To deploy NGINX Proxy Manager integrated with open-appsec using `docker-compose` (and optionally connect also to the central open-appsec WebUI) follow the steps below:

Available settings in the `.env` file allowing further customization of the deployment: