# Installing Agents via Docker Compose

This guide explains how to install agents via Docker Compose.

## Prerequisites

* Docker and Docker Compose are installed on your system.
* Connectware [license key](https://docs.cybus.io/2-1-0/documentation/installation-and-upgrades/licensing) is available.

{% hint style="warning" %}
If multiple agents are running on the same machine, each agent must be assigned its own Docker volume. Otherwise, agents will overwrite each other's persisted data, including credentials.
{% endhint %}

## Installation

1. Log in to the Cybus Docker registry. Enter the following command in your terminal:

{% code lineNumbers="true" %}

```bash
docker login registry.cybus.io
```

{% endcode %}

When prompted, enter the following credentials:

* **Username:** `license`
* **Password:** Your Connectware license key

2. Create a folder for your agent (e.g., `myAgent`).
3. Inside this folder, create a new file named `docker-compose.yml`.
4. Add the following configuration to your `docker-compose.yml` file:

{% hint style="info" %}
Replace `${IMAGE_TAG}` with the protocol-mapper agent image version you want to use (e.g., `2.1.0`).
{% endhint %}

{% code title="docker-compose.yml" lineNumbers="true" %}

```yaml
services:
  protocol-mapper-agent:
    image: registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}
    environment:
      CYBUS_AGENT_MODE: distributed
      CYBUS_AGENT_NAME: myAgent
      CYBUS_HOSTNAME_INGRESS: localhost
      CYBUS_TRUST_ALL_CERTS: true
    volumes:
      - protocol-mapper-agent:/data
    restart: unless-stopped
    network_mode: host
    hostname: <some-suitable-hostname>
volumes:
  protocol-mapper-agent:
```

{% endcode %}

5. In your terminal, run the following command to start the agent:

{% code lineNumbers="true" %}

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

{% endcode %}

**Result**

The agent is now installed and running. To verify, use:

{% code lineNumbers="true" %}

```bash
docker compose ps
```

{% endcode %}

This command lists running containers. You should see `protocol-mapper-agent` in the output.

## Configuration

### Environment Variables

Specify environment variable values in an `.env` file, placed in the same directory as your `docker-compose.yml`. For a comprehensive list of available environment variables, see [Environment Variables](https://docs.cybus.io/2-1-0/documentation/environment-variables).

#### Required Environment Variables

| Environment Variable     | Description                                        |
| ------------------------ | -------------------------------------------------- |
| `CYBUS_AGENT_MODE`       | Must be set to `distributed` to run in agent mode. |
| `CYBUS_AGENT_NAME`       | Unique identifier for this agent instance.         |
| `CYBUS_HOSTNAME_INGRESS` | IP address or hostname of the Connectware server.  |

#### Optional Environment Variables

| Environment Variable     | Default Value             | Description                                 |
| ------------------------ | ------------------------- | ------------------------------------------- |
| `CYBUS_MQTT_USERNAME`    | `<agentName>`             | Authentication username for Connectware.    |
| `CYBUS_DATAPLANE_SCHEME` | `mqtt`                    | MQTT connection scheme (`mqtts` or `mqtt`). |
| `CYBUS_DATAPLANE_PORT`   | MQTT `1883`, MQTTS `8883` | Port number for MQTT connection.            |

### Persisting Agent Credentials

Agent credentials are automatically persisted using the volume defined in your `docker-compose.yml`:

```yaml
volumes:
  protocol-mapper-agent:
```

The agent stores and retrieves credentials from this volume automatically.

{% hint style="warning" %}
If multiple agents are running on the same machine, each agent must have its own volume. Otherwise, agents will overwrite each other's credentials.
{% endhint %}

### Alternative: Setting a Password

As an alternative to generating credentials locally, you can set the `CYBUS_PROTOCOL_MAPPER_PASSWORD` environment variable. This is useful if the agent is managed by the same orchestration tool as your central Connectware instance.

In most cases, we recommend using local credentials stored in a volume and authenticated through the [client registration](https://docs.cybus.io/2-1-0/documentation/client-registry) process.

### Setting the Hostname

The hostname is displayed in the [Connectware UI](https://docs.cybus.io/2-1-0/documentation/agents/monitoring-agents). Set a custom hostname in your `docker-compose.yml`:

```yaml
services:
  protocol-mapper-agent:
    hostname: <some-suitable-hostname>
```

You can use the `${HOSTNAME}` environment variable if available on your system.

### Running with Root Permissions

To run the agent with root privileges (required for certain protocols like USB access or promiscuous network mode), add the `user` property:

```yaml
services:
  protocol-mapper-agent:
    user: root
```

## Security Configuration

### Enabling Mutual TLS (mTLS)

To use mutual TLS, add the environment variable to your `docker-compose.yml`:

```yaml
environment:
  CYBUS_USE_MUTUAL_TLS: true
```

For more information, see [Environment Variables](https://docs.cybus.io/2-1-0/documentation/environment-variables).

### Mounting Certificates

Mount your certificates as volumes. By default, the agent looks for certificates in these locations (configurable via environment variables):

| Environment Variable | Default Path                         |
| -------------------- | ------------------------------------ |
| `AGENT_KEY`          | `/connectware/certs/client/tls.key`  |
| `AGENT_CERT`         | `/connectware/certs/client/tls.crt`  |
| `CA`                 | `/connectware/certs/ca/ca-chain.pem` |

**Example**

```yaml
services:
  protocol-mapper-agent:
    volumes:
      - protocol-mapper-agent:/data
      - /path/to/certs:/connectware/certs:ro
```

## Network Requirements

Communication from the agent to the Connectware server is unidirectional, simplifying firewall rules and increasing security.

### Agent Container

The agent container does not require any incoming TCP/IP ports. It initiates all necessary outbound connections to the Connectware server.

### Outbound Connections

Ensure the following outbound TCP/IP connections are allowed from the agent's network:

* **443/tcp (HTTPS)**: For secure web communication
* One of the following:
  * **1883/tcp (MQTT)**: If using unencrypted MQTT
  * **8883/tcp (MQTTS)**: If using encrypted MQTT
* One of the following:
  * **4222/tcp**: If using mTLS authentication
  * **4223/tcp**: If using username & password authentication

The choice between MQTT and MQTTS depends on your `CYBUS_DATAPLANE_SCHEME` setting.

### Connectware Server

No special inbound firewall rules are required on the Connectware server, as the agent initiates all connections.