Skip to Content

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. The Troubleshoot section explains how to use the health check service on a running container, and gives some common issues and their solutions.

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:

The following examples show how to run multiple agents:

Important

The commands on this page are provided for testing purposes, or as the basis for further development. You should consult the Docker documentation for information on making them suitable for production systems.

Prerequisites

You must have the following for all examples on this page:

  • Docker

  • Your Harmony account username and password.

  • Your Harmony organization name.

Additionally, 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.

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

  2. 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"

  3. To check the status of your agent, refresh the Management Console > Agents page.

  4. In the terminal, press Control+C to stop the agent, or use the docker container stop command.

  5. (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.

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

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

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

  4. To check the status of your agent, refresh the Management Console > Agents page.

  5. In the terminal, press Control+C to stop the agent, or use the docker container stop command.

  6. (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 problems. It uses automatic registration to automatically add an agent to Harmony. The required registration values are passed into the container using environment variables (most of which are prefixed with AUTO_REGISTER). For authentication, you can use either an encrypted username/password pair, or an access token. (Both methods are shown here.)

  1. Choose an authentication method:

    1. 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=

    2. Copy the values for use in the next step (using the first line for AUTO_REGISTER_ENCRYPTED_USERNAME, and the second line for AUTO_REGISTER_ENCRYPTED_PASSWORD).

    3. 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=
    Example environment variable file 
    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=
    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 jitterbit-utils -e.
    AUTO_REGISTER_ENCRYPTED_PASSWORD The second line of output from jitterbit-utils -e.

    1. Select Management Console > Access Tokens from the Harmony Portal menu, then create an access token. Choose the environment that your private agent group is associated with, and set the scope to Agent Registration.

    2. Copy the token for setting the value of AUTO_REGISTER_TOKEN in the next step.

    3. 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_TOKEN=
    Example environment variable file 
    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_TOKEN=jb_d86ec8a0-0693-4392-b345-ef4e134dab42
    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_TOKEN Access token with scope Agent Registration.

  2. Run this command to start the containerized private agent, where FILE is the name of the file created in the previous step:

    docker run --detach --env-file FILE jitterbit/agent

    Tip

    To enable Jitterbit native observability with this method, add AUTO_REGISTER_AGENT_METRICS_TOKEN to the list of environment variables passed to the container. The value is an access token with scope Agent Metric.

  3. To check the status of your agent, refresh the Management Console > Agents page.

  4. To stop the agent, use the Management Console to drain stop the agent.

  5. To stop the container, find the container ID with docker ps, then use docker container stop CONTAINER_ID.

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

An alternative to using environment variables is to set the required values in a register.json file. This file can be placed in a conf subdirectory, from where the agent container reads it and uses it to register the agent. As with the previous example, you can authenticate using either a username and password, or an access token.

  1. Choose an authentication method:

    1. 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=

    2. Create a directory and file conf/register.json containing the following, with values set (highlighted) 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 first line of output from jitterbit-utils -e.
      password The second line of output from jitterbit-utils -e.
      Example conf/register.json 
      {
    "cloudUrl": "https://na-east.jitterbit.com",
    "agentGroupId": 12345,
    "username": "$00HD1uP3SoM3odoS5NklwBp3VBeg1O4COW31ohIMqBBfWOcUrlzADwMawtI8lAcg6C",
    "password": "$003k9pLM1SJvrnh4CeMzw6jBdzsr0TY6s92wNuMiBuIVs=",
    "agentNamePrefix": "test",
    "deregisterAgentOnDrainstop": false,
    "retryCount": 10,
    "retryIntervalSeconds": 5
}

    1. Select Management Console > Access Tokens from the Harmony Portal menu, then create an access token. Choose the environment that your private agent group is associated with, and set the scope to Agent Registration.

    2. Copy the token for setting the value of `` in the next step.

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

      conf/register.json
      {
    "cloudUrl": "https://REGION.jitterbit.com",
    "agentGroupId": GROUP_ID,
    "token": "ACCESS_TOKEN",
    "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.
      token Access token with scope Agent Registration.
      Example conf/register.json 
      {
    "cloudUrl": "https://na-east.jitterbit.com",
    "agentGroupId": 12345,
    "token": "jb_21b0cda9-18f7-4953-bd71-8616def9d6bd",
    "agentNamePrefix": "test",
    "deregisterAgentOnDrainstop": false,
    "retryCount": 10,
    "retryIntervalSeconds": 5
}

  2. Run this command to start the containerized private agent:

    docker run --detach --name jitterbit-agent --rm --volume ./conf:/conf jitterbit/agent

    Tip

    To enable Jitterbit native observability with this method, add the agentMetricsToken parameter to the register.json file. The value is an access token with scope Agent Metric.

  3. To check the status of your agent, refresh the Management Console > Agents page.

  4. To stop the agent, use the Management Console to drain stop the agent.

  5. To stop the container, find the container ID with docker ps, then use docker stop CONTAINER_ID.

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

  1. Create an environment variables file as shown above.

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

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

  4. To check the status of your agent, refresh the Management Console > Agents page.

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

  1. Start a Kubernetes cluster.

    Tip

    In Docker Desktop, select Settings > Kubernetes > Enable Kubernetes.

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

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

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
    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.

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

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

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

  6. Run this command to stop the cluster and remove the containers:

    helm uninstall private-agent-group

Environment variables

The following environment variables are recognized by the Jitterbit private agent Docker image:

Category Variable Required Default Allowed values Description
Login HARMONY_ORIGIN https://na-east.jitterbit.com
https://emea-west.jitterbit.com
https://apac-southeast.jitterbit.com		 The login URL for your Harmony account.
HARMONY_USERNAME String Your Harmony account username.
HARMONY_PASSWORD String Your Harmony account password.
HARMONY_ORG_NAME String Your Harmony organization name.
Agent identification HARMONY_AGENT_GROUP_NAME String The agent group name and environment name, separated by an underscore.
HARMONY_AGENT_NAME String The agent name.
Observability JITTERBIT_ENABLE_METRICS Datadog
Elasticsearch		 Enable private agent observability for the specified platform.
DD_API_KEY
(if JITTERBIT_ENABLE_METRICS=Datadog)		 String Datadog API key.
DD_SITE datadoghq String Datadog site URL.
DD_HOST_NAME Automatic (from system hostname) String Datadog agent hostname.
ES_API_KEY
(if JITTERBIT_ENABLE_METRICS=Elasticsearch)		 String Elasticsearch API key.
ES_URL
(if JITTERBIT_ENABLE_METRICS=Elasticsearch)		 String Elasticsearch URL.
METRICS_AGENT_NAME Automatic (from auto-register information) String Private agent name.
METRICS_AGENT_GROUP_NAME Automatic (from auto-register information) String Private agent group name.
METRICS_ENVIRONMENT_NAME Automatic (from auto-register information) String Environment name.
SKIP_METRICS_CONFIG String If true, don't automatically configure Jitterbit metrics. (Equivalent of jitterbit-config -k/--skip-metrics-config option.)
ENABLE_JITTERBIT_METRICS String If true, enable Jitterbit metrics. Ignored if SKIP_METRICS_CONFIG is true.

Ports

When running as a container, the following ports can be exposed:

Port Description
46908 Apache HTTP
46909 Apache HTTPS
46912 Tomcat server
3000 Health check service

Troubleshoot

Health check service

To see the status of a private agent, map port 3000 in the container to a local port, then issue an HTTP GET request to localhost on the mapped port. You can do this using the -p/--publish option in docker run commands, or by setting the ports key in docker compose commands:

Example
docker run -p 3000:3000 <other options> jitterbit/agent
Docker Compose example
services:
    agent:
        env_file: FILE
        image: jitterbit/agent
        container_name: jitterbit-agent
        ports:
            - "3000"

To call the service, use a web browser or curl to make a request on port 3000:

Docker run example
curl -i localhost:3000

The response is in JSON format, with fields indicating (as true or false) the overall status of the private agent, and the status of individual services:

Example response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 04 Aug 2025 09:10:11 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Content-Length: 112

{"agent":true,"servers":{"apache_http":true,"apache_https":true,"tomcat_http":true,"tomcat_shutdown_http":true}}

The HTTP response codes are as follows:

Code Description
200 Success (All services running)
500 Failure (One or more services not running)

Resources

These sections in the Troubleshoot page may help when troubleshooting private agents running on Docker: