Installing Agents via Docker Compose

How to install agents using Docker Compose.

This page explains how to install agents via Docker Compose.

Prerequisites

• Docker and Docker Compose are installed on your system.

• Connectware license key is available.

If multiple agents are running on the same host, each agent must be assigned its own Docker volume. Otherwise, agents will overwrite each other's persisted data, including credentials. Run them with bridge networking. See Network Mode.

Installation

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

docker login registry.cybus.io

When prompted, enter the following credentials:

• Username: license

• Password: Your Connectware license key

1. Create a folder for your agent (e.g., myAgent).

2. Inside this folder, create a new file named docker-compose.yml.

3. Add the following configuration to your docker-compose.yml file:

Replace ${IMAGE_TAG} with the protocol-mapper agent image version that matches your Connectware version, for example 2.6.0. Replace connectware.example.com with the address of your Connectware server.

docker-compose.yml

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: connectware.example.com
      CYBUS_TRUST_ALL_CERTS: true
    volumes:
      - protocol-mapper-agent:/data
    restart: unless-stopped
    network_mode: bridge
    hostname: <some-suitable-hostname>
volumes:
  protocol-mapper-agent:

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

docker compose up -d

Result

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

docker compose ps

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.

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:

volumes:
  protocol-mapper-agent:

The agent stores and retrieves credentials from this volume automatically.

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

Setting the Hostname

The hostname is displayed in the Connectware UI. Set a custom hostname in your docker-compose.yml:

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:

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:

environment:
  CYBUS_USE_MUTUAL_TLS: true

For more information, see 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

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.

Network Mode

Run agents with network_mode: bridge. Every agent binds port 8888 for its health probe and port 9184 for its metrics endpoint. In bridge mode each agent keeps those ports to itself, so any number of agents can run on the same host. Agents using network_mode: host share the host's ports, so only the first one to start binds them and the rest fail to start.

With bridge networking, localhost refers to the container, not the host. Set CYBUS_HOSTNAME_INGRESS to an address that reaches Connectware from inside the container. If Connectware runs on the same host, use the host's IP address.

Agent Container

The agent container does not require any incoming TCP/IP ports. It initiates all necessary outbound connections to the Connectware server. The health probe on port 8888 and the metrics endpoint on port 9184 bind inside the container and need no inbound firewall rule.

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.