# Connect Deployed Agents to SaaS Management (Docker)

## Prerequisites

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

{% content-ref url="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 bellow, 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="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 

* Existing open-appsec WAF deployment on Docker which is:
  * locally managed
  * not connected to the central WebUI yet

### Instructions: 

<details>

<summary>Optional: Perform One-Time Upload of Your Existing Local Configuration to Central WebUI If You Want to Maintain It (relevant for Central Management Mode Only)</summary>

If you want to maintain your existing local, declarative configuration after connecting to central WebUI, so that it will become the initial starting point for the central management configuration (requires WebUI deployment profile set to "This management"), follow these optional steps to perform a one time upload of your existing local, declarative configuration to the central management (SaaS).

{% hint style="warning" %}
*This option is not relevant when you want to connect to a deployment profile in central management WebUI set to "Declarative configuration", as in that case WebUI will continuously show the current, declarative configuration, which you will still manage locally.*
{% endhint %}

{% hint style="danger" %}
*If you do not perform this step and have the deployment profile set to "This management" you will start with a new clean (empty) central configuration for your existing deployment.*
{% endhint %}

#### Step 1: Download the `mgmt-connect-linux` tool

Run the following command to download and prepare the `mgmt-connect-linux` tool inside the existing, running agent container:

```bash
docker exec -it open-appsec-agent bash -c "wget https://downloads.openappsec.io/scripts/mgmt-connect-linux && chmod +x mgmt-connect-linux"
```

#### Step 2: Perform one-time upload of the existing local configuration

Use the token generated in your deployment profile during the prerequisites to upload the policy. Replace `<TOKEN>` with your actual deployment profile token:

```bash
docker exec -it open-appsec-agent bash -c "./mgmt-connect-linux --token <TOKEN> --config-upload-only"
```

**Notes:**

* The container name for the agent container in your environment could have been changed based on your original deployment, in that case adjust `open-appsec-agent` in the commands above with your own agent container name.

</details>

{% tabs %}
{% tab title="Docker Compose with .env" %}
**If you deployed open-appsec using docker-compose command with `.env` file):**

**Step 1:** Add the deployment profile's token to your `.env` file:

* Locate the `APPSEC_AGENT_TOKEN=` key in your `.env` file.
* Copy the **Token** from your WebUI Docker Profile (as described in the prerequisites) and paste it as the value for the `APPSEC_AGENT_TOKEN` key.

Example `.env` file snippet, make sure to do the above change in your own `.env` file and provide your own deployment profile token copied from the Web UI for `<your-agent-token>`:

```yaml
## To connect your deployment to central open-appsec WebUI provide the token for a profile
## which you created in open-appsec WebUI at https://my.openappsec.io
## Example: APPSEC_AGENT_TOKEN=111-22222-111
APPSEC_AGENT_TOKEN=<your-agent-token>
```

{% hint style="info" %}
If you chose "***“Declarative configuration”*** management make sure to keep the agent local configuration file volume mount which gets mounted to `/ext/appsec` inside the agent container.&#x20;

If you chose "**This Management**" then the above mentioned volume mount is no longer needed, and can be removed. &#x20;
{% endhint %}

**Step 2:** Apply the adjusted Docker Compose configuration provided in the `.env` file:\
Run the following commands to recreate the agent container based on the adjusted Docker Compose file which now includes the `AGENT_TOKEN` specification for connecting to Management WebUI (SaaS):

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

**Step 3:** Verify the connection:

* Log in to the Web UI and check if your agent is connected.
  {% endtab %}

{% tab title="Docker Compose without .env" %}
**If you deployed open-appsec using docker-compose command (without using a `.env` file):**

**Step 1:** Add the deployment profile's token to your `docker-compose.yaml` file:

* Locate the `AGENT_TOKEN` key in your `docker-compose.yaml` file.
* Copy the **Token** from your WebUI Docker Profile (as described in the prerequisites) and paste it as the value for the `AGENT_TOKEN` key.

Example `docker-compose.yaml` snippet, make sure to do the above change in your own `docker-compose.yaml` file providing your own deployment profile token copied from the Web UI for `<your-agent-token>`:

```yaml
version: '3'
services:
  openappsec-agent:
    image: ghcr.io/openappsec/agent:latest
    container_name: open-appsec-agent
    environment:
      - registered_server=NGINX Server
      - user_email=<add-your-email-here>
      - https_proxy=<user:password@proxy-address:port>
      - autoPolicyLoad=false
      - AGENT_TOKEN=<your-agent-token>
    volumes:
      - <path-to-persistent-location-for-agent-config>:/etc/cp/conf
      - <path-to-persistent-location-for-agent-data-files>:/etc/cp/data
      - <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent
      - <path-to-persistent-location-for-local-configuration-file>:/ext/appsec
    ipc: host
```

{% hint style="info" %}
If you chose "***“Declarative configuration”*** management make sure to keep the agent local configuration file volume mount which gets mounted to `/ext/appsec` inside the agent container.&#x20;

If you chose "**This Management**" then the above mentioned volume mount is no longer needed, and can be removed. &#x20;
{% endhint %}

**Step 2:** Apply the adjusted Docker Compose configuration:\
Run the following commands to recreate the agent container based on the adjusted Docker Compose file which now includes the `AGENT_TOKEN` specification for connecting to Management WebUI (SaaS):

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

**Step 3:** Verify the connection:

* Log in to the Web UI and check if your agent is connected.
  {% endtab %}
  {% endtabs %}

If you chose **“This management”** management mode, and didn't upload the policy:&#x20;

**Step 4:** Create one or more assets in the Web UI, make sure to connect the asset to the profile you have created in the Prerequisites:

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