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.

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

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.

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

  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 output for use 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_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=
    
  4. 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
    
  5. To check the status of your agent, refresh the Management Console > Agents page.

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

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

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

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

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

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

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

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

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

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