Run a Jitterbit private API gateway on Docker

Introduction

This section gives examples of different ways to run a private API gateway on Docker using Jitterbit's Docker image.

Prerequisites

Before you start, you need the following:

• Docker installed and running.

• A Harmony account, and its username, password, and organization ID.

• A valid API Manager API in the organization associated with the private API gateway.

• If running behind a forward proxy, configure your host's firewall to allow proxy server exceptions.

• (Optional) For automatic generation of TLS certificates, a registered custom gateway domain and its fully qualified domain name (FQDN) in the form mygateway.mydomain.com.

Interactive start and configure

Run the following to start the container, then respond to the prompts (which follows the Linux install configuration steps):

docker run --interactive --tty --name=jb-gateway \
--hostname=jb-gateway -p 80:80 -p 443:443 \
jitterbit/private-gateway

Interactive start and configure with bridge network

Run the following to create a bridge network and start the container connected to that network, then respond to the prompts:

docker network create -d bridge jitterbit

docker run --interactive -tty --name=jb-gateway \
--hostname=jb-gateway -p 80:80 -p 443:443 \
--network=jitterbit \
jitterbit/private-gateway

A bridge network offers the following advantages:

• Container Discovery: Allows for direct communication using container names, avoiding the reliance on IP addresses. This simplifies inter-container communication, and lets private agents communicate freely with private gateways.

• Better Isolation: Provides improved isolation, reducing the risk of accidental interactions between unrelated containers.

• Custom Configurations: Allows for specific network settings, such as subnet and gateway customization.

• Network Segmentation: Facilitates the segmentation of network traffic, ensuring containers on different bridge networks don't interfere with each other.

• Network Policies: Enables the application of distinct network rules or policies, offering enhanced control over container communications.

Unattended start with bridge network and configure with environment variables

Run the following to create a bridge network and start the container in detached mode, with values provided via environment variables:

docker network create -d bridge jitterbit

docker run --detach --name=jb-gateway \
--hostname=jb-gateway -p 80:80 -p 443:443 \
--network=jitterbit \
--env "HARMONY_USERNAME=<USERNAME>" \
--env "HARMONY_PASSWORD=<PASSWORD>" \
--env "ORGANIZATION_ID=<ORG_ID>" \
--env "SERVICE_URL=<SERVICE_URL>" \
--env "PROXY_ENABLED=true|false" \
--env "PROXY_HOSTNAME=<PROXY_HOSTNAME>"
--env "PROXY_USERNAME=<PROXY_SERVER_USERNAME>" \
--env "PROXY_PASSWORD=<PROXY_SERVER_PASSWORD>" \
--env "LETS_ENCRYPT_ENABLED=true|false" \
--env "LETS_ENCRYPT_DOMAIN=<DOMAIN>" \
--env "LETS_ENCRYPT_EMAIL=<EMAIL>" \
jitterbit/private-gateway

Set the variable values as follows:

Unattended start and configure with an environment variables file

Follow these steps to start the container in detached mode with environment variables set in a file:

1. In the directory where Docker runs, create a subdirectory conf. In it, create a file gateway.conf containing the following environment variables:

   conf/gateway.conf

   ##
   # Jitterbit Private API Gateway Docker configuration
   # For more information, see https://docs.jitterbit.com/api-gateways/private-api-gateway/docker/
   ##
   
   ## Jitterbit API Gateway Configuration
   #
   # Your Harmony account username. (Usually your email address.)
   HARMONY_USERNAME=
   # Your Harmony account password.
   # IMPORTANT: Follow your shell's quoting and escape rules for passwords with special characters.
   # Example: 'P@5$w0rD'
   HARMONY_PASSWORD=
   # Your Harmony account organization ID.
   # Example: 12345
   ORGANIZATION_ID=
   # The Jitterbit service URL for your Harmony account region, one of the following:
   # - For NA: https://services.jitterbit.net/apis
   # - For EMEA: https://services.jitterbit.eu/apis
   # - For APAC: https://services.jitterbit.cc/apis
   SERVICE_URL=
   
   ## Proxy Configuration (Optional)
   #
   # When true, enable proxy.
   PROXY_ENABLED=false
   ## When PROXY_ENABLED=true, uncomment and set the following:
   #
   # Proxy server URL, as http://your_proxy_server:port
   # PROXY_HOSTNAME=
   # Proxy server username
   # PROXY_USERNAME=
   # Proxy server password
   # PROXY_PASSWORD=
   
   ## Let's Encrypt certificates
   # When true, enable automatic generation of TLS certificate.
   # IMPORTANT: You must first create a DNS record pointing to the public IP address of your server.
   LETS_ENCRYPT_ENABLED=true
   # Fully-qualified domain name of your server, matching the A record or CNAME of the DNS record.
   # Example: gateway.mydomain.com
   LETS_ENCRYPT_DOMAIN=
   # Used by Lets Encrypt to issue the certificate. (Usually your email address.)
   LETS_ENCRYPT_EMAIL=
   

2. Set the variable values as in the previous example.

3. Run the following command:

   docker run --detach --name=jb-gateway -p 80:80 -p 443:443 \
   -v "$(pwd)/conf:/conf" \
   jitterbit/private-gateway
   

4. (Optional) Test the gateway.

Test

You can test a running Docker private API gateway using a health check, or the self-test utility.

Health check

To ensure a private API gateway functions as expected, first test an API Manager API's service URL using the cloud gateway, then test the private API gateway's URL for the same endpoint:

1. In API Manager in the organization associated with the private API gateway, create and publish an API.

2. Using an API test tool or command, make an HTTPS GET request to the API's service URL.

   For example, for organization name JBExample, organization ID 123456, environment URL prefix development, API version number 1, and healthProbe service root, the API's service URL would be https://JBExample123456.jitterbit.net/development/v1/healthProbe in the NA region.

3. Make the call again, but replace your organization name and ID and the Harmony region domain name (jitterbit.net, jitterbit.cc, or jitterbit.eu) with your gateway's subdomain and domain.

   Using the previous example with a gateway domain of mysubdomain.example.com results in a private API gateway URL of https://mysubdomain.example.com/development/v1/healthProbe.

Self-test utility

The gateway's built-in self-test utility runs through a series of automatic tests that include importing a built-in project and API and then calling the API through the gateway to ensure proper configuration.

The API is created with the SSL only option enabled, meaning access to the private API gateway URL will be tested over HTTPS only. To allow access over HTTP, you can disable the SSL only option in the API configuration after the test API is created.

An API URL must be available in your subscription for the self-test to be successful.

To run the self-test utility, follow these steps:

1. Open a shell session on a running container:

   docker exec -it jitterbit-gateway bash
   

2. Execute the self-test utility:

   /usr/bin/jitterbit-api-gateway-config --test