Jitterbit private agents on Docker

Introduction

The examples on this page show you how to run one or more containerized private agents using Jitterbit's Docker hub image.

Note

The Docker image is not updated at the same time as the Windows or Linux agent packages. Refer to the image's tags page to see what versions are available.

The following examples show how to run a single agent:

Quick start
Manual registration with environment variables
Automatic registration with environment variables
Automatic registration with register.json file

The following examples show how to run multiple agents:

Multiple agents with Docker compose
Multiple agents with Helm and Kubernetes

Important

Use the commands on this page for testing or as the basis for further development, and consult the Docker documentation for information on making them suitable for production systems.

Prerequisites

You must have the following:

Docker
Your Harmony account username and password.
Your Harmony organization name.

You must have the following to run the multiple agent examples:

Quick start

This example uses the jitterbit-config command to prompt for the agent's registration information, the jitterbit command to start the agent, and tail -F to wait for and show the agent log file.

Select Management Console > Agents from the Harmony Portal menu, then add a private agent group, or note the name and ID of an existing one.

In a terminal, run this command and respond to the prompts:

docker run -it jitterbit/agent sh -c "jitterbit-config; jitterbit start; tail -F log/jitterbit-agent.log"

To check the status of your agent, refresh the Management Console > Agents page.
In the terminal, press Control+C to stop the agent, or use the docker container stop command.
(Optional) Delete the agent using the Management Console. (Agents started in this way are not automatically removed when stopped.)

Manual registration with environment variables

In the Quick start example, you must enter the agent's registration information when prompted. In this example, this information is provided using environment variables.

Add an agent to your agent group and note its name.

Create a file containing the following, with values set according to the table below:

HARMONY_ORIGIN=
HARMONY_USERNAME=
HARMONY_PASSWORD=
HARMONY_ORG_NAME=
HARMONY_AGENT_GROUP_NAME=
HARMONY_AGENT_NAME=

Variable	Value Description
`HARMONY_ORIGIN`	The login URL for your Harmony account, `https://REGION.jitterbit.com`, where `REGION` is one of `na-east`, `emea-west`, or `apac-southeast`.
`HARMONY_USERNAME`	Your Harmony account username.
`HARMONY_PASSWORD`	Your Harmony account password.
`HARMONY_ORG_NAME`	Your Harmony organization name.
`HARMONY_AGENT_GROUP_NAME`	The agent group name and environment name, separated by an underscore.
`HARMONY_AGENT_NAME`	The agent name.

Example

HARMONY_ORIGIN=https://na-east.jitterbit.com
HARMONY_USERNAME=example@jbexample.com
HARMONY_PASSWORD=P@55w0rd
HARMONY_ORG_NAME=Example Org
HARMONY_AGENT_GROUP_NAME=Example Agent Group_Example Env
HARMONY_AGENT_NAME=Example Agent 1

In a terminal, run this command to start the agent, replacing FILE with the name of the file created in step 2:
```
docker run --env-file FILE jitterbit/agent
```
To check the status of your agent, refresh the Management Console > Agents page.
In the terminal, press Control+C to stop the agent, or use the docker container stop command.
(Optional) Delete the agent using the Management Console. (Agents started in this way are not automatically removed when stopped.)

Automatic registration with environment variables

There are two disadvantages with the manual registration example: you must manually add an agent in the Management Console, and your Harmony credentials are visible to anyone with access to the system.

This example avoids both of these. It uses automatic registration to automatically add an agent to Harmony. Your Harmony credentials are encrypted and passed with the other required registration values to the container using a different set of environment variables.

In a terminal, run the following jitterbit-utils command to encrypt your credentials, replacing USERNAME and PASSWORD with your Harmony username and password:

docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD

Example command

docker run jitterbit/agent jitterbit-utils -e example@jbexample.com P@55w0rd

Example output

$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=

Copy the output for use in the next step.

Create a file containing the following, with values substituted according to the table below:

HARMONY_ORIGIN=
AUTO_REGISTER=true
AUTO_REGISTER_AGENT_GROUP_ID=
AUTO_REGISTER_AGENT_NAME_PREFIX=auto
AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
AUTO_REGISTER_ENCRYPTED_USERNAME=
AUTO_REGISTER_ENCRYPTED_PASSWORD=

Variable	Value description
`HARMONY_ORIGIN`	The login URL for your Harmony account, `https://REGION.jitterbit.com`, where `REGION` is one of `na-east`, `emea-west`, or `apac-southeast`.
`AUTO_REGISTER_AGENT_GROUP_ID`	The agent group ID number.
`AUTO_REGISTER_ENCRYPTED_USERNAME`	The first line of output from step 1.
`AUTO_REGISTER_ENCRYPTED_PASSWORD`	The second line of output from step 1.

Example

HARMONY_ORIGIN=https://na-east.jitterbit.com
AUTO_REGISTER=true
AUTO_REGISTER_AGENT_GROUP_ID=12345
AUTO_REGISTER_AGENT_NAME_PREFIX=auto
AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP=false
AUTO_REGISTER_ENCRYPTED_USERNAME=$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C
AUTO_REGISTER_ENCRYPTED_PASSWORD=$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=

Run this command to start the containerized private agent, where FILE is the name of the file created in step 2:
```
docker run --detach --env-file FILE jitterbit/agent
```
To check the status of your agent, refresh the Management Console > Agents page.
To stop the agent, use the Management Console to drain stop the agent.
To stop the container, find the container ID with docker ps, then use docker container stop CONTAINER_ID.
If AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP is set to true, the agent is automatically removed when stopped. If not, delete the agent in the Management Console.

Automatic registration with `register.json` file

This example shows an alternative to registering with environment variables is to use a register.json file.

Run the jitterbit-utils command to encrypt your Harmony username and password:
```
docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
```
Tip

You can use the same encrypted username and password output from the previous example.

Create a directory and file conf/register.json containing the following, with values set according to the table below:

conf/register.json

{
    "cloudUrl": "https://REGION.jitterbit.com",
    "agentGroupId": GROUP_ID,
    "username": "ENCRYPTED_USERNAME",
    "password": "ENCRYPTED_PASSWORD",
    "agentNamePrefix": "test",
    "deregisterAgentOnDrainstop": false,
    "retryCount": 10,
    "retryIntervalSeconds": 5
}

Parameter	Value description
`cloudUrl`	The login URL for your Harmony account, `https://REGION.jitterbit.com`, where `REGION` is one of `na-east`, `emea-west`, or `apac-southeast`).
`agentGroupId`	The agent group ID number.
`username`	The encrypted username (first line of output from step 1).
`password`	The encrypted password (second line of output from step 1).

Example conf/register.json

{
    "cloudUrl": "https://na-east.jitterbit.com",
    "agentGroupId": 12345,
    "username": "$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C",
    "password": "$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=",
    "agentNamePrefix": "test",
    "deregisterAgentOnDrainstop": false,
    "retryCount": 10,
    "retryIntervalSeconds": 5
}

Tip

An agent started this way uses the default settings in the Docker image's jitterbit.conf file. Without persistence, any changes you make to this file inside the container are lost when the container stops. To use your own settings, put them in conf/jitterbit.conf. This file is copied into the container when it starts, overwriting the default file.

Run this command to start the containerized private agent:
```
docker run --detach --name jitterbit-agent --rm --volume ./conf:/conf jitterbit/agent
```
Important

The private agent fails to start if the conf directory contains both a credentials.txt file and a register.json file.
To check the status of your agent, refresh the Management Console > Agents page.
To stop the agent, use the Management Console to drain stop the agent.
To stop the container, find the container ID with docker ps, then use docker stop CONTAINER_ID.
If deregisterAgentOnDrainstop is set to true, the agent is automatically removed when stopped. If not, delete the agent in the Management Console.

Multiple agents with `docker compose`

In this example, three private agents with identical configurations run in an agent group.

Create an environment variables file as shown above.

Create a file docker-compose.yml containing the following:

docker-compose.yml

services:
    agent1:
        env_file: FILE
        image: jitterbit/agent
        container_name: jitterbit-agent1
    agent2:
        env_file: FILE
        image: jitterbit/agent
        container_name: jitterbit-agent2
    agent3:
        env_file: FILE
        image: jitterbit/agent
        container_name: jitterbit-agent3

FILE: The name of the environment variable file created in step 1.

Run this command to start the private agent group:
```
docker compose up -d
```
Tip

Run docker compose logs -f to watch the log files from all agents, or docker stats to monitor each agent's resource usage.
To check the status of your agent, refresh the Management Console > Agents page.
Run this command to stop the private agent group and remove their containers:
```
docker compose down -d
```

Multiple agents with `helm` and `kubernetes`

Jitterbit provide a Helm chart that you can use to run a cluster of agents using Kubernetes.

Start a Kubernetes cluster.

Tip

In Docker Desktop, select Settings > Kubernetes > Enable Kubernetes.
Run this command to encrypt your Harmony username and password:
```
docker run jitterbit/agent jitterbit-utils -e USERNAME PASSWORD
```
Tip

You can use the same output from previous examples.

Create a file values.yaml containing the following, with values substituted according to the table below:

nameOverride: private-agent-group

image:
  repository: jitterbit/agent
  pullPolicy: always

agent:
  registerjson:
    cloudUrl: "https://REGION.jitterbit.com"
    agentGroupId: GROUP_ID
    username: ENCRYPTED_USERNAME
    password: ENCRYPTED_PASSWORD
    agentNamePrefix: "test"
    deregisterAgentOnDrainstop: true

hpa:
  enabled: true
  minReplicas: 3
  maxReplicas: 5

replicas: 4

Line	Value	Replace with
9	`REGION`	Your Harmony account region (`na-east`, `emea-west`, or `apac-southeast`).
10	`GROUP_ID`	The agent group ID number.
11	`ENCRYPTED_USERNAME`	The first line of output from step 2.
12	`ENCRYPTED_PASSWORD`	The second line of output from step 2.

Caution

This configuration specifies that Kubernetes should run at least 3 and at most 5 agents if the Horizontal Pod Autoscaler is active, or 4 agents if not. As each Docker private agent needs approximately 0.25 CPU cores and 2 GB of memory, you should check your host's specifications can support this number of agents. You can also add a resources element to set the limits of resource utilization. For more details, see Jitterbit's example value.yml file.

Run these commands to add and update the Helm chart repository:

helm repo add jitterbit https://jitterbit.github.io/charts
helm repo update

Run this command to start the private agent cluster:
```
helm upgrade -i -f values.yaml private-agent-group jitterbit/agent-group
```
Tip

Run kubectl -n default get pods --watch to monitor the cluster status, or kubectl exec -it private-agent-group-0 -- curl localhost:46912/axis/v1/cdk/internal/members to list the members of the listening service's cluster.
Run this command to stop the cluster and remove the containers:
```
helm uninstall private-agent-group
```