Skip to main content
  1. CoffeeBean Technology
  2. On-Premise Agent
  3. About the Agent

Agent Installation Guide

Introduction

The CoffeeBean agent is a Docker-based software installed on operating systems and responsible to act as a connector between CoffeeBean Platform and on premise services such as LDAP servers (e.g. Active Directory, OpenLDAP and others) and databases (MySQL, Microsoft SQL Server, Oracle and others).

The CoffeeBean agent must be installed on a machine (virtual or not) and it must have direct access to the on premise services.
 

It’s recommended to install at least two agents on different servers to provide redundancy for the integration.

 

Firewall

The agent does not need to receive inbound requests. It opens a persistent connection (websocket) to the CoffeeBean Platform using HTTPS (443) and performs requests on demand to the services using the configured hosts and ports.

 

Example for a local LDAP Server:

 


 

In summary, the outbound requirements are:

  • HTTPS: 443
  • LDAP: 389 (LDAP) or 636 (LDAPS) or any custom port
  • SQL: 3306 (MySQL), 1433 (SQL Server) or any custom port
     

Probably you also need to open more outbound and maybe inbound ports to perform operating system management tasks, such as package updates, monitoring, time sync, etc., but it is out of the CBT agent scope.
 

If you apply firewall restrictions based on domain names, you need to allow the following ones:

  • *.coffeebeantech.com
  • *.socialidnow.com

 

Some domains are used only during initial setup, such as:

  • *.docker.com
  • *.githubusercontent.com
  • *.github.com
  • *.gallery.ecr.aws

 

System Requirements

It is recommended to install the agent into a system with the following requirements:

 

  • Processor: 1 vCPU
  • Memory: 1 GB RAM
  • Storage: 5 GB SSD
  • Operating system: any Linux distribution (Debian, Ubuntu, SUSE, CentOS, RedHat) supporting Docker

 

The agent is a component which needs approximately 500 MB of storage space (without logs) and consumes approximately 150 MB of memory during execution.
 

You also need to scale your server or virtual machine with memory and storage for the chosen operating system and system/agent logs.
 

Scalability

It is recommended to install at least two agents on distinct hosts to ensure high availability and failover.

 

Each agent can handle an average of 150 requests per minute (rpm) for simple operations. Deploy as many agents as needed to meet your performance requirements.
 

Configuration Requirements

You can configure one or more services in the same agent according to your company needs:

LDAP Configuration

You’ll need the following information:

  • LDAP server settings: host, port and base domain (e.g. dc=yourdomain,dc=com).

  • Credentials (full distinguished name/password) of an LDAP admin user with permission to perform all required LDAP operations.

  • The agent registration endpoint available in the Administrative Portal.

 

SQL Configuration

You’ll need the following information:
 

  • SQL server settings: driver, host, port and database name.
    Note: When the driver is sqlserver and a port is needed, inform the host in the format host:port and leave the port field blank.

  • Credentials of a SQL user with permission to perform all required SQL operations.

  • The agent registration endpoint available in the Administrative Portal.

 

HTTP Configuration

You’ll need the following information:

Setup for Active Directory

For the correct behavior between the agent and the Active Directory to happen, there are some important configurations to setup:

  • Active Directory has an option to automatically renew the password for access. To ensure that the agent won’t stop working when deployed it’s necessary to disable the auto renewing of the Active Directory password.
  • When the agent is deployed, it’s important to let it import or export information on it’s own. When data is replicated outside of the agent flow, duplicated entries may appear on the database, which is not optimal for production environments.

Docker

The agent is managed using Docker containers. Follow this section for further details.

 

Repository

The latest CBT Agent images are available in the following repository:

https://gallery.ecr.aws/cbt/cbt-agent

 

Download

Pull the image:

docker pull public.ecr.aws/cbt/cbt-agent:<version>

 

Example using latest agent version:

docker pull public.ecr.aws/cbt/cbt-agent:0.0.7

 

Configure

Run the configuration command:

docker run -it --rm \

-e LOG_DIR="<container_log_dir>" \

-e CONFIG_DIR="<container_config_dir>" \

-v "<host_log_dir>:<container_log_dir>" \

-v "<host_config_dir>:<container_config_dir>" \

public.ecr.aws/cbt/cbt-agent:<version> <command>

 

Available commands:

  • LDAP configuration: ldap-agent-register
  • SQL configuration: sql-agent-register
  • HTTP configuration: http-agent-register
     

Example for LDAP configuration using latest agent version:

docker run -it --rm \

-e LOG_DIR="/var/log/cbt-ldap-agent" \

-e CONFIG_DIR="/etc/cbt-ldap-agent" \

-v "/var/log/cbt-ldap-agent:/var/log/cbt-ldap-agent" \

-v "/etc/cbt-ldap-agent:/etc/cbt-ldap-agent" \

public.ecr.aws/cbt/cbt-agent:0.0.7 ldap-agent-register

 

Run

Run the agent as a container:

docker run -d --name <container_name> \

-e LOG_DIR="<container_log_dir>" \

-e CONFIG_DIR="<container_config_dir>" \

-v "<host_log_dir>:<container_log_dir>" \

-v "<host_config_dir>:<container_config_dir>" \

public.ecr.aws/cbt/cbt-agent:<version> ldap-agent

Example using latest agent version:

docker run -d --name cbt-agent-container \

-e LOG_DIR="/var/log/cbt-ldap-agent" \

-e CONFIG_DIR="/etc/cbt-ldap-agent" \

-v "/var/log/cbt-ldap-agent:/var/log/cbt-ldap-agent" \

-v "/etc/cbt-ldap-agent:/etc/cbt-ldap-agent" \

public.ecr.aws/cbt/cbt-agent:0.0.7 ldap-agent


 

Manage

Manage the agent container:

docker <command> <container_name>

 

Commands:

  • start
  • stop
  • restart
     

Example: starting the agent container:

docker start cbt-agent-container

 

Update

When a new release is available, it’s recommended to stop all running containers and clean up containers and images:

  1. Stop running containers:
     

docker ps -a

docker stop <container-name>

  1. Clean up Docker containers:

docker system prune -a

 

Multiple Agents

If you have two or more environments, you can run multiple docker containers with different configurations. See the example below, with agents for staging and production environments:
 

LDAP configuration commands:

docker run -it --rm \

-e LOG_DIR="/var/log/cbt-ldap-agent" \

-e CONFIG_DIR="/etc/cbt-ldap-agent" \

-v "/var/log/cbt-ldap-agent-staging:/var/log/cbt-ldap-agent" \

-v "/etc/cbt-ldap-agent-staging:/etc/cbt-ldap-agent" \

public.ecr.aws/cbt/cbt-agent:0.0.7 ldap-agent-register

 

docker run -it --rm \

-e LOG_DIR="/var/log/cbt-ldap-agent" \

-e CONFIG_DIR="/etc/cbt-ldap-agent" \

-v "/var/log/cbt-ldap-agent-production:/var/log/cbt-ldap-agent" \

-v "/etc/cbt-ldap-agent-production:/etc/cbt-ldap-agent" \

public.ecr.aws/cbt/cbt-agent:0.0.7 ldap-agent-register

 

Run commands:

docker run -d --name cbt-agent-container-staging \

-e LOG_DIR="/var/log/cbt-ldap-agent" \

-e CONFIG_DIR="/etc/cbt-ldap-agent" \

-v "/var/log/cbt-ldap-agent-staging:/var/log/cbt-ldap-agent" \

-v "/etc/cbt-ldap-agent-staging:/etc/cbt-ldap-agent" \

public.ecr.aws/cbt/cbt-agent:0.0.7 ldap-agent

 

docker run -d --name cbt-agent-container-production \

-e LOG_DIR="/var/log/cbt-ldap-agent" \

-e CONFIG_DIR="/etc/cbt-ldap-agent" \

-v "/var/log/cbt-ldap-agent-production:/var/log/cbt-ldap-agent" \

-v "/etc/cbt-ldap-agent-production:/etc/cbt-ldap-agent" \

public.ecr.aws/cbt/cbt-agent:0.0.7 ldap-agent


Manage commands:

docker start cbt-agent-container-staging

 

docker start cbt-agent-container-production

 

Docker Compose

You can use Docker Compose to help to define and manage Docker containers like cbt-agent-container.
 

With Docker Compose your containers can be configured to automatically run again if the operating system restarts, for example.

Install

To download and install the Compose CLI plugin, run:
 

$ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}


$ mkdir -p $DOCKER_CONFIG/cli-plugins


curl -SL https://github.com/docker/compose/releases/download/v2.35.0/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose

 

Apply executable permissions to the binary:

 

$ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

Test the installation:

 

$ docker compose version
Docker Compose version v2.29.7

 

Configure

Now see docker-compose.yaml structure, made docker-compose.yaml file in your preferred folder:

$ vim docker-compose.yaml

version: '3.3'
services:
    cbt-agent-container:
        container_name: cbt-agent-container
        command: ldap-agent
        environment:
            - LOG_DIR=/var/log/cbt-ldap-agent
            - CONFIG_DIR=/etc/cbt-ldap-agent
        volumes:
            - '/var/log/cbt-ldap-agent:/var/log/cbt-ldap-agent'
            - '/etc/cbt-ldap-agent:/etc/cbt-ldap-agent'
        restart: always
        logging:
            options:
                max-size: 1g
        image: public.ecr.aws/cbt/cbt-agent:0.0.7

IMPORTANT: do not remove this command "restart: always", because it is required for recovery container in case the machine restarts

 

Run

To install cbt-agent run:
 

$ docker compose up -d

 

If want see logs run:
 

$ docker compose logs

 

Ensure your docker service is enabled as a service to start with the system. Example using systemctl:

 

$ systemctl enable docker

 

Manage

More commands:

  • start
  • stop
  • restart
  • ps

Multiple Agents

If you have two or more environments, you can insert more services in docker-compose.yaml, look this example, having agents for staging and production environments:
 

$ vim docker-compose.yaml


version: '3.3'
services:
    cbt-agent-container-staging:
        container_name: cbt-agent-container-staging
        command: ldap-agent
        environment:
            - LOG_DIR=/var/log/cbt-ldap-agent
            - CONFIG_DIR=/etc/cbt-ldap-agent
        volumes:
            - '/var/log/cbt-ldap-agent-staging:/var/log/cbt-ldap-agent'
            - '/etc/cbt-ldap-agent-staging:/etc/cbt-ldap-agent'
        restart: always #never-remove
        logging:
            options:
                max-size: 1g
        image: public.ecr.aws/cbt/cbt-agent:0.0.7


    cbt-agent-container-production:
        container_name: cbt-agent-container-production
        command: ldap-agent
        environment:
            - LOG_DIR=/var/log/cbt-ldap-agent
            - CONFIG_DIR=/etc/cbt-ldap-agent
        volumes:
            - '/var/log/cbt-ldap-agent-production:/var/log/cbt-ldap-agent'
            - '/etc/cbt-ldap-agent-production:/etc/cbt-ldap-agent'
        restart: always #never-remove
        logging:
            options:
                max-size: 1g
        image: public.ecr.aws/cbt/cbt-agent:0.0.7

 

If you want to see logs run:

$ docker compose logs cbt-agent-container-staging


$ docker compose logs cbt-agent-container-production

Uninstall

Clean up container with docker-compose:
 

$ docker compose down

To remove docker-compose use:
 

$ rm $DOCKER_CONFIG/cli-plugins/docker-compose

 

 

Installer (Deprecated)

Download

You can download and run the latest version with the following command:


 

\curl -sSL https://raw.githubusercontent.com/coffeebeantech/cbt-agent-installer/master/cbt-agent.sh | bash


 

Install

Upon downloading the installer script, it will present a list of options for you to choose from.

Start by selecting option "Docker/image installation" to install the agent.

 

Usage

After installation, you can run the agent manager with the "cbt-agent" command.

 

Configure

You can configure one or more services in the same agent according to your company needs:

LDAP Configuration

In the options menu, select option "LDAP configuration" and follow the instructions to register the LDAP agent.

SQL Configuration

In the options menu, select option "SQL configuration" and follow the instructions to register the SQL agent.

 

Run

In the options menu, select option "Service execution" to start the agent in background mode.

 

Manage

In the options menu, select option "Service management" to open the management menu.

From there you can start / stop / restart the service (background mode) and check the service status and logs.


 

 

Português do Brasil