# Install With Docker (Centrally Managed)

{% hint style="warning" %}
Deployment of open-appsec via `docker run` is now considered deprecated. Please deploy with Docker Compose instead following these instructions: [deploy-with-docker-compose](https://docs.openappsec.io/getting-started/start-with-docker/deploy-with-docker-compose "mention")
{% endhint %}

## 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, and make sure to choose the "**This management**" management mode. \
  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 %}

* Linux machine with:
  * Docker software installed (or similar compatible Container runtime)
  * Root Permissions 

## Installation

{% tabs %}
{% tab title="NGINX" %}
{% hint style="warning" %}
Make sure to meet the prerequisites on top of this page and to have the profile token available. Make sure you enforce the policy after profile creation.
{% endhint %}

**Follow these steps to deploy open-appsec and NGINX reverse proxy (including open-appsec attachment) with separate containers (e.g. on Docker) or implement this using your deployment CI pipeline:**\
(This is the standard deployment, an alternative option to deploy with a single, unified container is available as well, see "NGINX - Unified" tab.)

**Step 1:** Pull the open-appsec agent image or add/use it as part of the deployment CI’s container management system:

```bash
docker pull ghcr.io/openappsec/agent:latest
```

**Step 2:** Create the following empty directories to be used later for volume mounts in the docker run command for the agent.

```
<path-to-persistent-location-for-agent-config>
<path-to-persistent-location-for-agent-data-files>
<path-to-persistent-location-for-agent-debugs-and-logs>
```

{% hint style="info" %}
Creation of the folders above and the volume mounts shown in the next step with `-v` is optional but strongly recommended for having persistence of the important agent information (data, config, logs).
{% endhint %}

**Step 3:** Run the open-appsec agent container with this command:

<pre class="language-bash"><code class="lang-bash"><strong>docker run --name=open-appsec-agent \
</strong>--ipc=host \
-v &#x3C;path-to-persistent-location-for-agent-config>:/etc/cp/conf \
-v &#x3C;path-to-persistent-location-for-agent-data-files>:/etc/cp/data \
-v &#x3C;path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent \
-it \
-e registered_server='NGINX' \
-e user_email=&#x3C;your-email-address> \
-e AGENT_TOKEN=&#x3C;token> \
-e https_proxy=&#x3C;user:password@proxy address:port> \
-d ghcr.io/openappsec/agent:latest /cp-nano-agent
</code></pre>

Replace the `<token>` parameter with the token you copied from the profile in the WebUI before (see Prerequisites section above).&#x20;

The `https_proxy` environment variable allows you to configure an HTTP(S) proxy server to be used by the agent. It is optional and can be removed if not needed.

The optional `no-upgrade` flag to the `cp-nano-agent` command will start the agent without an initial upgrade.&#x20;

{% hint style="info" %}
The optional `user_email` environment variable allows you to associate your email address with your specific deployment by replacing `<your-email-address>` 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.
{% endhint %}

**Step 3:** Create (or replace) the NGINX container by first pulling the open-appsec NGINX container, which already contains the open-appsec attachment. Alternatively, add/use it as part of the deployment CI’s container management system:

```bash
docker pull ghcr.io/openappsec/nginx-attachment:latest
```

**Step 4:** Run the open-appsec NGINX container, make sure to add the `--ipc=host` parameter, here’s an example command:

```bash
docker run --name open-appsec-nginx \
--ipc=host \
-p 80:80 \
-d ghcr.io/openappsec/nginx-attachment:latest
```

{% hint style="info" %}
For general NGINX configuration please check the relevant [NGINX documentation](https://nginx.org/en/docs/)
{% endhint %}

**Step 5:** Make sure both containers are running, use `docker ps` to verify.

**Step 6:** Navigate to the Agents tab and ensure the new Agent is successfully connected.

**Step 7:** Create one or more assets defining the specific resources that open-appsec should protect and don't forget to install the policy afterward. \
All required steps are explained here:

{% content-ref url="../../using-the-web-ui-saas/protect-additional-assets" %}
[protect-additional-assets](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/protect-additional-assets)
{% endcontent-ref %}
{% endtab %}

{% tab title="NGINX - Unified (beta)" %}
{% hint style="info" %}
This feature is currently in beta and may be subject to changes.
{% endhint %}

{% hint style="warning" %}
Make sure to meet the prerequisites on top of this page and to have the profile token available. Make sure you enforce the policy after profile creation.
{% endhint %}

**Follow these steps to deploy open-appsec combined with NGINX reverse proxy (including open-appsec attachment) with a single, unified container (e.g. on Docker) or implement this using your deployment CI pipeline:**

**Step 1:** Pull the open-appsec agent unified with NGINX image or add/use it as part of the deployment CI’s container management system:

```bash
docker pull ghcr.io/openappsec/agent-unified:latest
```

**Step 2:** Create the following empty directories to be used later for volume mounts in the docker run command for the agent.

```
<path-to-persistent-location-for-agent-config>
<path-to-persistent-location-for-agent-data-files>
<path-to-persistent-location-for-agent-debugs-and-logs>
```

{% hint style="info" %}
Creation of the folders above and the volume mounts shown in the next step with `-v` is optional but strongly recommended for having persistence of the important agent information (data, config, logs).
{% endhint %}

**Step 3:** Run the open-appsec agent container with this command:

```bash
docker run -d \
  --name open-appsec-agent-unified \
  --restart unless-stopped \
  -p 80:80 \
  -p 443:443 \
  -v <path-to-persistent-location-for-agent-config>:/etc/cp/conf \
  -v <path-to-persistent-location-for-agent-data-files>:/etc/cp/data \
  -v <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent \
  -v <host-nginx-conf-path>:/etc/nginx/conf.d \
  -e user_email=<your-email-address> \
  -e AGENT_TOKEN=<token> \
  -e https_proxy=<user:password@proxy address:port> \
  ghcr.io/openappsec/agent-unified:latest /cp-nano-agent
```

Replace the `<token>` parameter with the token you previously copied from the profile in the WebUI (see Prerequisites section above).

The `https_proxy` environment variable allows you to configure an HTTP(S) proxy server to be used by the agent. It is optional and can be removed if not needed.

The optional `no-upgrade` flag to the `cp-nano-agent` command will start the agent without an initial upgrade.&#x20;

{% hint style="info" %}
The optional `user_email` environment variable allows you to associate your email address with your specific deployment by replacing `<your-email-address>` 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.
{% endhint %}

{% hint style="info" %}
For general NGINX configuration please check the relevant [NGINX documentation](https://nginx.org/en/docs/)
{% endhint %}

**Step 3:** Make sure both containers are running, use `docker ps` to verify.

**Step 4:** Navigate to the Agents tab and ensure the new Agent is successfully connected.

**Step 5:** Create one or more assets defining the specific resources that open-appsec should protect and don't forget to install the policy afterward. \
All required steps are explained here:

{% content-ref url="../../using-the-web-ui-saas/protect-additional-assets" %}
[protect-additional-assets](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/protect-additional-assets)
{% endcontent-ref %}
{% endtab %}

{% tab title="Kong" %}
{% hint style="warning" %}
For Kong, as alternative to the traditional open-appsec attachment plugin, also a newer, more flexible Lua-based plugin is available, deployment instructions are available here:\
[deploy-with-docker-compose](https://docs.openappsec.io/getting-started/start-with-docker/deploy-with-docker-compose "mention")
{% endhint %}

{% hint style="warning" %}
Make sure to meet the prerequisites on top of this page and to have the profile token available. Make sure you enforced the policy after profile creation.
{% endhint %}

**Follow these steps to install Kong with open-appsec using containers (e.g. on Docker) or using your deployment CI:**

**Step 1:** Pull the open-appsec agent image or add/use it as part of the deployment CI’s container management system:

```bash
docker pull ghcr.io/openappsec/agent:latest
```

**Step 2:** The volume mounts set in the next step with`-v` are optional but recommended for the persistence of the agent information (data, config, logs).\
If you want to use those parameters create the following empty directories to be used later for volume mounts in the docker run command for the agent.

```
<path-to-persistent-location-for-agent-config>
<path-to-persistent-location-for-agent-data-files>
<path-to-persistent-location-for-agent-debugs-and-logs>
```

**Step 3:** Run the open-appsec agent container with this command:

```bash
docker run --name=open-appsec-agent \
--ipc=host \
-v <path-to-persistent-location-for-agent-config>:/etc/cp/conf \
-v <path-to-persistent-location-for-agent-data-files>:/etc/cp/data \
-v <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent \
-it \
-e registered_server='Kong' \
-e user_email=<your-email-address> \
-e AGENT_TOKEN=<token> \
-e https_proxy=<user:password@proxy address:port> \
-d ghcr.io/openappsec/agent:latest /cp-nano-agent
```

Replace the `<token>` parameter with the token you copied from the profile in the WebUI before (see Prerequisites section above).

The `https_proxy` environment variable allows you to configure an HTTP(S) proxy server to be used by the agent. It is optional and can be removed if not needed.

The optional `no-upgrade` flag to the `cp-nano-agent` command will start the agent without an initial upgrade.&#x20;

{% hint style="info" %}
The volume mounts set with`-v` are optional but recommended for the persistence of the agent information (data, config, logs).\
If you use those parameters create the following empty directories to be used later for volume mounts in the docker run command for the agent.

```
<path-to-persistent-location-for-agent-config>
<path-to-persistent-location-for-agent-data-files>
<path-to-persistent-location-for-agent-debugs-and-logs>
```

The optional `user_email` environment variable allows you to associate your email address with your specific deployment by replacing `<your-email-address>` with your own email address.

This allows us 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.
{% endhint %}

**Step 3:** Create (or replace) the Kong container by pulling the enhanced open-appsec Kong container, which already contains the open-appsec attachment. Alternatively, add/use it as part of the deployment CI’s container management system:

For Kong (open-source version):

```bash
docker pull ghcr.io/openappsec/kong-attachment:latest
```

For Kong Gateway (enterprise version):

```bash
docker pull ghcr.io/openappsec/kong-gateway-attachment:latest
```

**Step 4:** Run the open-appsec Kong container, make sure to add the `--ipc=host` parameter, here’s an example command:

For Kong (open-source version):

```bash
docker run \
--name kong \
--ipc=host \
-e KONG_DATABASE=off \
-p 8000:8000 -p 8443:8443 -p 127.0.0.1:8001:8001 -p 127.0.0.1:8444:8444 \
-d ghcr.io/openappsec/kong-attachment:latest
```

For Kong Gateway (enterprise version):

```bash
docker run \
--name kong-gateway \
--ipc=host \
-e KONG_DATABASE=off \
-p 8000:8000 -p 8443:8443 -p 127.0.0.1:8001:8001 -p 127.0.0.1:8444:8444 \
-d ghcr.io/openappsec/kong-gateway-attachment:latest
```

{% hint style="info" %}
For general Kong configuration details please check the [Kong documentation](https://docs.konghq.com)&#x20;
{% endhint %}

**Step 5:** Make sure both containers are running, use `docker ps` to verify.

**Step 6:** Navigate to the Agents tab and ensure the new Agent is successfully connected.

**Step 7:** Create one or more assets defining the specific resources that open-appsec should protect and don't forget to enforce the policy afterward. \
All required steps are explained here:

{% content-ref url="../../using-the-web-ui-saas/protect-additional-assets" %}
[protect-additional-assets](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/protect-additional-assets)
{% endcontent-ref %}
{% endtab %}

{% tab title="APISIX" %}
{% hint style="warning" %}
A new, enhanced version of the docker compose for APISIX\
is available here: [deploy-with-docker-compose](https://docs.openappsec.io/getting-started/start-with-docker/deploy-with-docker-compose "mention") (Currently in Early Availability)
{% endhint %}

{% hint style="warning" %}
Make sure to meet the prerequisites on top of this page and to have the profile token available. Make sure you enforced the policy after profile creation.
{% endhint %}

**Follow these steps to install APISIX with open-appsec using containers (e.g. on Docker) or using your deployment CI:**

**Step 1:** Download the docker-compose.yaml file, see content bellow:&#x20;

```
wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/apisix/docker-compose.yaml
```

```
version: "3"

services:
  apisix:
    container_name: apisix
    image: "ghcr.io/openappsec/apisix-attachment:latest"
    ipc: host
    restart: always
    volumes:
      - .<apisix-conf-path>:/usr/local/apisix/conf/apisix.yaml:ro
    environment:
      - APISIX_STAND_ALONE=true
    ports:
      - "9180:9180/tcp"
      - "9080:9080/tcp"
      - "9091:9091/tcp"
      - "9443:9443/tcp"

  appsec-agent:
    container_name: appsec-agent
    image: 'ghcr.io/openappsec/agent:latest'
    ipc: host
    restart: unless-stopped
    environment:
      # adjust with your own email below
      - user_email=user@email.com
      - registered_server="APISIX"
      - AGENT_TOKEN=<TOKEN>
    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 
```

**Step 2:** Replace the following:

* &#x20;Replace the `<TOKEN>` parameter with the token you copied from the profile in the WebUI before (see Prerequisites section above),&#x20;
* Replace `<apisix-conf-path>` with the path for declarative configuration file for APISIX, an example file can be found [here](https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/apisix/apisix-example-config/apisix-standalone.yaml), for general APISIX configuration details please check the [APISIX Documentation](https://apisix.apache.org/docs/docker/manual/).

{% hint style="info" %}

* The volume mounts are optional but recommended for the persistence of the agent information (data, config, logs).
* The optional `user_email` environment variable allows you to associate your email address with your specific deployment by replacing `<your-email-address>` with your own email address. This allows us 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.
  {% endhint %}

**Step 3:** Run the Docker Compose

```
docker-compose up -d
```

**Step 4:** Make sure both containers are running, use `docker ps` to verify.

**Step 5:** Navigate to the Agents tab and ensure the new Agent is successfully connected.

**Step 6:** Create one or more assets defining the specific resources that open-appsec should protect and don't forget to enforce the policy afterward. \
All required steps are explained here:

{% content-ref url="../../using-the-web-ui-saas/protect-additional-assets" %}
[protect-additional-assets](https://docs.openappsec.io/getting-started/using-the-web-ui-saas/protect-additional-assets)
{% endcontent-ref %}
{% endtab %}

{% tab title="Envoy" %}
For Envoy deployment on Docker please follow the docs for `docker-compose`-based installation provided here:

{% content-ref url="../deploy-with-docker-compose" %}
[deploy-with-docker-compose](https://docs.openappsec.io/getting-started/start-with-docker/deploy-with-docker-compose)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}

{% hint style="success" %}
Now your open-appsec installation on Docker is completed and your configured web app or API assets are protected!
{% endhint %}