Run a 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:

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://success.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 the health probe endpoint, or the self-test utility.

Health probe endpoint¶

To call the gateway health probe endpoint, first test the API Manager API's service URL, then the private API gateway's URL:

1. Using an API test tool or command, make an HTTPS GET request on the healthProbe endpoint of the API Manager API's service URL.

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

2. Make the call again, but replace your organization name and ID, and jitterbit.net with your gateway's subdomain and domain.

   Using the previous example with a gateway domain of mysubdomain.example.com results in a health probe endpoint of https://mysubdomain.example.com/development/v1/healthProbe.

Self-test utility¶

To run the gateway's built-in 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