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 (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.
Tip
Use the same network to run your Docker-based private agents.
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:
Variable | Description | Example |
---|---|---|
HARMONY_USERNAME | Harmony account login. | name@example.com |
HARMONY_PASSWORD | Harmony account password. | P@5$w0rd |
ORGANIZATION_ID | Harmony organization ID number. | 12345 |
SERVICE_URL | Jitterbit service URL for your region:
| https://services.jitterbit.eu/apis |
PROXY_ENABLED | Enable proxy (true or false ). | true |
PROXY_HOSTNAME | Proxy hostname and port. | host.docker.internal:12121 |
PROXY_USERNAME | Proxy server username. | $(PROXY_SERVER_USERNAME) |
PROXY_PASSWORD | Proxy server password. | $(PROXY_SERVER_PASSWORD) |
LETS_ENCRYPT_ENABLED | Enable Let's Encrypt (true or false ). | true |
LETS_ENCRYPT_DOMAIN | Let's Encrypt domain name. | gateway.mydomain.com |
LETS_ENCRYPT_EMAIL | Let's Encrypt account email. | youremail@<mydomain>.com |
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:
-
In the directory where Docker runs, create a subdirectory
conf
. In it, create a filegateway.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=
-
Set the variable values as in the previous example.
-
Run the following command:
docker run --detach --name=jb-gateway -p 80:80 -p 443:443 \ -v "$(pwd)/conf:/conf" \ jitterbit/private-gateway
-
(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:
-
In API Manager in the organization associated with the private API gateway, create and publish an API.
-
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 ID123456
, environment URL prefixdevelopment
, API version number 1, andhealthProbe
service root, the API's service URL would behttps://JBExample123456.jitterbit.net/development/v1/healthProbe
in the NA region. -
Make the call again, but replace your organization name and ID and the Harmony region domain name (
jitterbit.net
,jitterbit.cc
, orjitterbit.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 ofhttps://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. 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:
-
Open a shell session on a running container:
docker exec -it jitterbit-gateway bash
-
Execute the self-test utility:
/usr/bin/jitterbit-api-gateway-config --test