# Deploy With Docker-Compose ## Prerequisites * **Linux Docker Host with root permission** * **Docker-Compose tool installed** #### Optional (Recommended) Prerequisites: * **Access to a SaaS tenant on my.openappsec.io (WebUI for SaaS management)**\ Follow the instructions available here: {% content-ref url="../using-the-web-ui-saas/sign-up-and-login-to-portal" %} [sign-up-and-login-to-portal](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/sign-up-and-login-to-portal) {% endcontent-ref %} * **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: {% content-ref url="../using-the-web-ui-saas/create-a-profile" %} [create-a-profile](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/create-a-profile) {% endcontent-ref %} ## Deployment #### To deploy open-appsec with docker-compose and optionally connect to the central WebUI available at follow the steps below: 1. Create a folder for your new open-appsec deployment and switch to that folder, e.g. ```bash mkdir open-appsec-deployment cd ./open-appsec-deployment ``` 2. Download the docker compose file for your desired open-appsec integration {% tabs %} {% tab title="NGINX" %} {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx/docker-compose.yaml ``` {% endcode %} {% embed url="" %} {% endtab %} {% tab title="NGINX - Unified" %} {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-unified/docker-compose.yaml ``` {% endcode %} {% embed url="" %} {% endtab %} {% tab title="Kong (traditional)" %} {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/kong/docker-compose.yaml ``` {% endcode %} {% hint style="warning" %} This deployment is for the traditional open-appsec integration with Kong.\ The Kong container specified in the `.env` file already contains the traditional open-appsec attachment which integrates on NGINX level and allows the open-appsec agent to inspect **all traffic** passing through Kong. You don't have to configure anything additionally in the Kong configuration for the agent to see the traffic. A new version of the Kong plugin based on Lua is now available as well, see separate tab. This is more flexible, as you can apply the attachment to specific traffic (e.g. selected routes only) and this is aligned with the official Kong plugin guidelines. {% endhint %} {% embed url="" %} {% endtab %} {% tab title="Kong (Lua plugin, beta)" %} 
wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/kong-lua-plugin/docker-compose.yaml
{% hint style="warning" %} This deployment is for the new, more flexible version of the Kong plugin based on Lua. This is more flexible than the traditional plugin (also still available, but will be deprecated in the future) and is following the official Kong plugin guidelines. The Kong container specified in the `.env` file does already contain the new Lua-based Kong plugin and is loading it as part of the included `kong.conf` file. As this is a regular Kong plugin, you must make sure to also configure the plugin to apply to your traffic (e.g. all traffic, specific routes, etc.), as otherwise the open-appsec agent will not receive the traffic for inspection. {% endhint %} {% embed url="" %} {% endtab %} {% tab title="APISIX" %} 
wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/apisix/docker-compose.yaml
{% embed url="" %} {% endtab %} {% tab title="Envoy (beta)" %} {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/envoy/docker-compose.yaml ``` {% endcode %} {% embed url="" %} {% endtab %} {% endtabs %} 3. Download the `.env` file for your desired open-appsec integration and adjust the configuration to your requirements as described below: {% tabs %} {% tab title="NGINX" %} * Download the default `.env` file here: {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx/.env ``` {% endcode %} {% embed url="" %} * **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 WebUI at all (resulting in standalone, locally, declaratively managed deployment). * Replace `user@email.com` 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](#prerequisites "mention") 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 WebUI at all, resulting in standalone, locally- and declaratively-managed deployment. {% hint style="warning" %} **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)! {% endhint %} {% hint style="info" %} The additional containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to 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](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-local-tuning-in-standalone-deployments "mention") {% endhint %} `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: {% hint style="warning" %} 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! {% endhint %} **USER\_EMAIL:** (Optional) Associate your email address with your specific deployment by replacing `user@email.com` 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). **APPSEC\_POSTGRES\_VERSION**: Allows you to set the postgres database version by specifying the postgres container tag. E.g. `APPSEC_POSTGRES_VERSION=18`\ It is not recommended to set this to latest, as changing the postgres major version does require an upgrade of the postgres database to be performed first.\ You find the steps to upgrade you postgres version used in your open-appsec deployment on docker here: [upgrade-postgres-version-docker-compose](https://docs.openappsec.io/deployment-and-upgrade/upgrade-postgres-version-docker-compose "mention") **Additional configuration available specifically for this integration type:** **NGINX\_CONFIG**: Set the directory on the docker host used for the volume mount to the NGINX `conf.d` directory. Make sure to have a valid NGINX configuration file default.conf in the mounted directory.\ \ 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). {% hint style="info" %} You find some additional advanced configuration options described within the `docker-compose.yaml` file as comments. {% endhint %} {% endtab %} {% tab title="NGINX - Unified" %} * Download the default `.env` file here: {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/nginx-unified/.env ``` {% endcode %} {% embed url="" %} * **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 WebUI at all (resulting in standalone, locally, declaratively managed deployment). * Replace `user@email.com` 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](#prerequisites "mention") 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 WebUI at all, resulting in standalone, locally- and declaratively-managed deployment. {% hint style="warning" %} **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)! {% endhint %} {% hint style="info" %} The additional containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to 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](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-local-tuning-in-standalone-deployments "mention") {% endhint %} `juiceshop` : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. {% hint style="warning" %} 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! {% endhint %} **USER\_EMAIL:** (Optional) Associate your email address with your specific deployment by replacing `user@email.com` 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:** **NGINX\_CONFIG**: Set the directory on the docker host used for the volume mount to the NGINX `conf.d` directory. Make sure to have a valid NGINX configuration file default.conf in the mounted directory. 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). {% hint style="info" %} You find some additional advanced configuration options described within the `docker-compose.yaml` file as comments. {% endhint %} {% endtab %} {% tab title="Kong (traditional)" %} * Download the default `.env` file here: {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/kong/.env ``` {% endcode %} {% embed url="" %} * **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 WebUI at all (resulting in standalone, locally, declaratively managed deployment). * Replace `user@email.com` 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](#prerequisites "mention") 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 WebUI at all, resulting in standalone, locally- and declaratively-managed deployment. {% hint style="warning" %} **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)! {% endhint %} {% hint style="info" %} The additional containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to 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](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-local-tuning-in-standalone-deployments "mention") {% endhint %} `juiceshop` : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. {% hint style="warning" %} 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! {% endhint %} **USER\_EMAIL:** (Optional) Associate your email address with your specific deployment by replacing `user@email.com` 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:** **KONG\_CONFIG**: Set the directory on the docker host used for the volume mount to the Kong `/opt/kong` directory. Make sure to have a valid Kong declarative configuration file kong.yaml in the mounted directory. 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). {% hint style="info" %} You find some additional advanced configuration options described within the `docker-compose.yaml` file as comments. {% endhint %} {% endtab %} {% tab title="Kong (Lua plugin, beta)" %} * Download the default `.env` file here: {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/kong-lua-plugin/.env ``` {% endcode %} {% embed url="" %} * **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 WebUI at all (resulting in standalone, locally, declaratively managed deployment). * Replace `user@email.com` 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](#prerequisites "mention") 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 WebUI at all, resulting in standalone, locally- and declaratively-managed deployment. {% hint style="warning" %} **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)! {% endhint %} {% hint style="info" %} The additional containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to 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](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-local-tuning-in-standalone-deployments "mention") {% endhint %} `juiceshop` : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. {% hint style="warning" %} 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! {% endhint %} **USER\_EMAIL:** (Optional) Associate your email address with your specific deployment by replacing `user@email.com` 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:** **KONG\_CONFIG**: Set the directory on the docker host used for the volume mount to the Kong `/opt/kong` directory. Make sure to have a valid Kong declarative configuration file kong.yaml in the mounted directory. 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). {% hint style="info" %} You find some additional advanced configuration options described within the `docker-compose.yaml` file as comments. {% endhint %} {% endtab %} {% tab title="APISIX" %} * Download the default `.env` file here: {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/apisix/.env ``` {% endcode %} {% embed url="" %} * **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 WebUI at all (resulting in standalone, locally, declaratively managed deployment). * Replace `user@email.com` 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](#prerequisites "mention") 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 WebUI at all, resulting in standalone, locally- and declaratively-managed deployment. {% hint style="warning" %} **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)! {% endhint %} {% hint style="info" %} The additional containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to 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](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-local-tuning-in-standalone-deployments "mention") {% endhint %} `juiceshop` : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. {% hint style="warning" %} 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! {% endhint %} **USER\_EMAIL:** (Optional) Associate your email address with your specific deployment by replacing `user@email.com` 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:** **APISIX\_CONFIG**: Set the directory on the docker host used for the APISIX configuration file mount to the APISIX file path `/usr/local/apisix/conf/apisix.yaml`. Make sure to have a valid apisix configuration for APISIX in standalone mode in the mounted file. 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). {% hint style="info" %} You find some additional advanced configuration options described within the `docker-compose.yaml` file as comments. {% endhint %} {% endtab %} {% tab title="Envoy (Beta)" %} * Download the default `.env` file here: {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/envoy/.env ``` {% endcode %} {% embed url="" %} * **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 WebUI at all (resulting in standalone, locally, declaratively managed deployment). * Replace `user@email.com` in the .env file with your own email. (More details below.) {% hint style="warning" %} When providing your own envoy.yaml configuration file, make sure to add the required configuration to load the open-appsec attachment filter! Follow these instructions:\ [load-the-attachment-in-proxy-configuration](https://docs.openappsec.io/deployment-and-upgrade/load-the-attachment-in-proxy-configuration "mention") {% endhint %} #### 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](#prerequisites "mention") 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 WebUI at all, resulting in standalone, locally- and declaratively-managed deployment. {% hint style="warning" %} **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)! {% endhint %} {% hint style="info" %} The additional containers introduce some additional functionality, which is relevant for standalone deployments only (already available when connected to 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](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-local-tuning-in-standalone-deployments "mention") {% endhint %} `juiceshop` : This will deploy an additional, vulnerable juiceshop-backend container that can be used for demo and testing purposes. {% hint style="warning" %} 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! {% endhint %} **USER\_EMAIL:** (Optional) Associate your email address with your specific deployment by replacing `user@email.com` 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:** **ENVOY\_CONFIG**: Set the directory on the docker host used for the Envoy configuration file mount to the Envoy file path `/envoy.yaml`. Make sure to have a valid envoy.yaml configuration file for Envoy in the mounted file path. 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). {% hint style="warning" %} When providing your own envoy.yaml configuration file, make sure to add the required configuration to load the open-appsec attachment filter! Follow these instructions:\ [load-the-attachment-in-proxy-configuration](https://docs.openappsec.io/deployment-and-upgrade/load-the-attachment-in-proxy-configuration "mention") {% endhint %} **ENVOY\_CONCURRENCY**: Allows setting the desired amount of Envoy worker processes. I order to use this parameter, specify this in the `.env` file and also adjust the "command" line for the appsec-envoy container in the `docker-compose.yaml` file (see additional comments in that file).\ Make sure to also adjust the following two parameters `ENVOY_CONCURRENCY_CALC` and `ENVOY_CONCURRENCY_NUMBER` accordingly if you adjusted `ENVOY_CONCURRENCY`. **ENVOY\_CONCURRENCY\_CALC**: Only relevant if you made a custom configuration for the amount of Envoy worker threads using the optional ENVOY\_CONCURRENCY parameter (see also explanation in docker-compose.yaml). In this case you must set `ENVOY_CONCURRENCY_CALC=custom` and then also provide the specified amount of Envoy worker threads in the `ENVOY_CONCURRENCY_NUMBER` parameter.\ This will make sure that the open-appsec attachment will create the right amount of transaction handlers.\ Possible values for `ENVOY_CONCURRENCY_CALC`: "numOfCores" (default), "custom" **ENVOY\_CONCURRENCY\_NUMBER**: Only relevant if you made a custom configuration for the amount of Envoy worker threads using the optional ENVOY\_CONCURRENCY parameter (see also explanation in docker-compose.yaml). See explanation for `ENVOY_CONCURRENCY_CALC` for more details. {% hint style="info" %} You find some additional advanced configuration options described within the `docker-compose.yaml` file as comments. {% endhint %} {% endtab %} {% endtabs %} 4. If you decided to locally, declaratively manage open-appsec with `local_policy.yaml` file: \ \ Download the initial declarative configuration file for open-appsec into new subfolder `./appsec-localconfig`:
```bash mkdir ./appsec-localconfig wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/prevent/local_policy.yaml -O ./appsec-localconfig/local_policy.yaml ``` {% hint style="info" %} 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\_policy.yaml* file set to detect-learn mode.\ \ (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-learn`for better detection accuracy and strongly reduced false positives.\ \ Read more about this here: \ [track-learning-and-move-from-learn-detect-to-prevent](https://docs.openappsec.io/how-to/configuration-and-learning/track-learning-and-move-from-learn-detect-to-prevent "mention") {% endhint %} 5. (only relevant when upgrading existing postgres database) Postgres database upgrade instructions {% hint style="warning" %} This is ONLY relevant if ALL of the following applies to your current deployment: * you are redeploying/ugprading an existing open-appsec deployment\ (this is not relevant for new deployments) * your current deployment is a standalone deployment\ (without a web UI profile token provided in the `.env` file, when connecting to web UI with a profile token typically there should not be any local postgres database being deployed/used) * your current deployment has the docker.compose `standalone` profile set in the `.env` file\ (otherwise postgres container wouldn't be deployed) * you now want to use a newer postgres image version, which is a new major release\ (which means database conversion is required) {% endhint %} * If all of the above applies, make sure to perform a postgres database upgrade following the steps provided here: [upgrade-postgres-version-docker-compose](https://docs.openappsec.io/deployment-and-upgrade/upgrade-postgres-version-docker-compose "mention") 6. Perform the deployment {% hint style="warning" %} This docker-compose file requires a postgres container version ≥ 18 due to changes in the postgres database path. If you already have a postgres container with tag "latest" of an earlier version in your local registry, make sure to pull the latest container image first, also it is highly recommended to specify a specific postgres major release version tag in the `.env` file, e.g. `APPSEC_POSTGRES_VERSION=18` {% endhint %} ```bash docker-compose up -d ``` You will see output similar to the below.\ Note that the amount of container will vary based between deployments with and without connection to central WebUI.\ \ ![](https://1225393248-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNcZmX14M2KdTBrq9EOnI%2Fuploads%2F6XGKyZOzn5m8dsouztve%2Fimage.png?alt=media\&token=6b0788ea-27ce-445f-be89-6ed0d6355995) 7. 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. ```bash docker ps ``` You will see output similar to the below:

docker ps example output with all containers up

**Congratulations, you successfully deployed open-appsec WAF integrated with the reverse proxy solution of your choice!** {% hint style="info" %} 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](https://docs.openappsec.io/getting-started/using-the-advanced-machine-learning-model "mention") {% endhint %} ## Recommended next steps: * **If you connected to central WebUI AND configured your deployment profile in the WebUI to "This management" mode for centrally managing open-appsec configuration**:\ \ **Create one or more assets in the WebUI** which represent web applications and/or Web APIs which you want to be protected by open-appsec WAF and allows you to adjust the open-appsec configuration specifically for each of them.
Make sure to link your assets to the specific WebUI Profile which you created earlier (General -> Profiles) and adjust the Threat Prevention mode to Detect-Learn or Prevent (Threat Prevention -> Mode), the steps are described here: \ \ [protect-additional-assets](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/protect-additional-assets "mention") {% hint style="warning" %} Don't forget to Enforce policy in the WebUI after you did any changes for those changes to become effective! {% endhint %} * **If you decided to locally, declaratively manage open-appsec (with or without connection to central WebUI in "Declarative configuration" mode):**\ \ Follow the steps described here to configure your open-appsec deployment using the `local_policy.yaml` file: \ \ [configuration-using-local-policy-file-docker](https://docs.openappsec.io/getting-started/start-with-docker/configuration-using-local-policy-file-docker "mention")\ \ In case you connected your locally managed deployment also to the central WebUI in "Declarative Configuration" mode, you can check security logs and view agent status and configuration also in the central WebUI at . {% hint style="warning" %} Don't forget to apply the policy using `open-appsec-ctl -ap` in the open-appsec-agent container or by setting `APPSEC_AUTO_POLICY_LOAD` in the `.env` file to `true` for automatic application of any configuration changes done in the `local_policy.yaml` file for the changes to become effective! {% endhint %}