# 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](/2-1-2/documentation/installation-and-upgrades/licensing.md) 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](/2-1-2/documentation/environment-variables.md).

#### 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](/2-1-2/documentation/client-registry.md) process.

### Setting the Hostname

The hostname is displayed in the [Connectware UI](/2-1-2/documentation/agents/monitoring-agents.md). 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](/2-1-2/documentation/environment-variables.md).

### 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cybus.io/2-1-2/documentation/agents/installing-agents/installing-agents-via-docker-compose.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.