Introduction
This guide walks through downloading, installing, and starting Kong Enterprise using Docker. The configuration shown in this guide is intended only as an example. You will want to modify and take additional measures to secure your Kong Enterprise system before moving to a production environment.
Docker images for Kong Enterprise are hosted on Bintray. In order to download a Kong Enterprise Docker image, you will need valid Bintray credentials.
Prerequisites
To complete this guide you will need:
- Docker
- Bintray credentials (Your Sales or Support contact will email your Bintray credential to you.)
- A valid Kong Enterprise license file (accessed via Bintray)
Step 1. Download Kong Enterprise
-
Obtain your Bintray API Key
Log in to Bintray
Hover over your user name in the top navigation bar and select “Edit Profile” from the dropdown.
From the Profile page, select “API Key” from the sidebar.
Submit your Bintray password and copy your API key to your clipboard.
-
Log in to Docker and pull the image
$ docker login -u <bintray_username> -p <bintray_API_key> kong-docker-kong-enterprise-edition-docker.bintray.io $ docker pull kong-docker-kong-enterprise-edition-docker.bintray.io/kong-enterprise-edition
This will pull the latest edition of Kong Enterprise. To pull a specific version of Kong Enterprise add the
<VERSION>
to the url:$ docker pull kong-docker-kong-enterprise-edition-docker.bintray.io/kong-enterprise-edition/<VERSION>
-
Run
docker images
to find the ID for the Kong Enterprise image. -
Tag the image ID for easier use in the commands that follow:
$ docker tag <IMAGE_ID> kong-ee
-
Create a Docker network (optional)
Containers require a network in order to discover and communicate with each other. To use this functionality create a network using the following command, replacing kong-ee-net with the name of your network:
$ docker network create kong-ee-net
Step 2. Export your Kong Enterprise License
-
Download your license file
If you do not already have your license file, you can download it from your Kong repository in Bintray. This typically follows the following pattern, with
being your company name. https://bintray.com/kong/<YOUR_REPO_NAME>/license#files
If you cannot locate your Kong repository on Bintray please contact your Sales or Support contact.
-
Copy the license data in its entirety and export it as a shell variable:
export KONG_LICENSE_DATA='{"license":{"signature":"LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tClZlcnNpb246IEdudVBHIHYyCgpvd0did012TXdDSFdzMTVuUWw3dHhLK01wOTJTR0tLWVc3UU16WTBTVTVNc2toSVREWk1OTFEzVExJek1MY3dTCjA0ek1UVk1OREEwc2pRM04wOHpNalZKVHpOTE1EWk9TVTFLTXpRMVRVNHpTRXMzTjA0d056VXdUTytKWUdNUTQKR05oWW1VQ21NWEJ4Q3NDc3lMQmorTVBmOFhyWmZkNkNqVnJidmkyLzZ6THhzcitBclZtcFZWdnN1K1NiKzFhbgozcjNCeUxCZzdZOVdFL2FYQXJ0NG5lcmVpa2tZS1ozMlNlbGQvMm5iYkRzcmdlWFQzek1BQUE9PQo9b1VnSgotLS0tLUVORCBQR1AgTUVTU0FHRS0tLS0tCg=","payload":{"customer":"Test Company Inc","license_creation_date":"2017-11-08","product_subscription":"Kong Enterprise","admin_seats":"5","support_plan":"None","license_expiration_date":"2017-11-10","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU"},"version":1}}'
Step 3. Configure the Database
Kong Enterprise requires a database and supports either Cassandra or PostgreSQL.
-
Instantiate a database:
If you are using Cassandra:
$ docker run -d --name kong-ee-database \ --network=kong-ee-net \ - p 9042:9042 \ cassandra:3
If you are using PostgreSQL:
$ docker run -d --name kong-ee-database \ --network=kong-ee-net \ -p 5432:5432 \ -e "POSTGRES_USER=kong" \ -e "POSTGRES_DB=kong" \ -e "POSTGRES_PASSWORD=kong" \ -e "POSTGRES_HOST_AUTH_METHOD=trust" \ postgres:9.6
-
Run Kong migrations:
Cassandra:
$ docker run --rm --network=kong-ee-net \ -e "KONG_DATABASE=cassandra" \ -e "KONG_PG_HOST=kong-ee-database" \ -e "KONG_CASSANDRA_CONTACT_POINTS=kong-ee-database" \ -e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \ kong-ee kong migrations bootstrap
PostgreSQL:
$ docker run --rm --network=kong-ee-net \ -e "KONG_DATABASE=postgres" \ -e "KONG_PG_HOST=kong-ee-database" \ -e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \ kong-ee kong migrations bootstrap
Docker on Windows users: Instead of the
KONG_LICENSE_DATA
environment variable, use the volume bind option. For example, assuming you’ve saved yourlicense.json
file intoC:\temp
, use--volume /c/temp/license.json:/etc/kong/license.json
to specify the license file.
Step 5. Configure and Start Kong Enterprise
-
Configure and Start Kong Enterprise:
Cassandra:
$ docker run -d --name kong-ee --network=kong-ee-net \ -e "KONG_DATABASE=cassandra" \ -e "KONG_PG_HOST=kong-ee-database" \ -e "KONG_CASSANDRA_CONTACT_POINTS=kong-ee-database" \ -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \ -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \ -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \ -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \ -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \ -e "KONG_PORTAL=on" \ -e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \ -p 8000:8000 \ -p 8443:8443 \ -p 8001:8001 \ -p 8444:8444 \ -p 8002:8002 \ -p 8445:8445 \ -p 8003:8003 \ -p 8004:8004 \ kong-ee
PostgreSQL:
$ docker run -d --name kong-ee --network=kong-ee-net \ -e "KONG_DATABASE=postgres" \ -e "KONG_PG_HOST=kong-ee-database" \ -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \ -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \ -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \ -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \ -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \ -e "KONG_PORTAL=on" \ -e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \ -p 8000:8000 \ -p 8443:8443 \ -p 8001:8001 \ -p 8444:8444 \ -p 8002:8002 \ -p 8445:8445 \ -p 8003:8003 \ -p 8004:8004 \ kong-ee
Docker on Windows users: Instead of the
KONG_LICENSE_DATA
environment variable, use the volume bind option. For example, assuming you’ve saved yourlicense.json
file intoC:\temp
, use--volume /c/temp/license.json:/etc/kong/license.json
to specify the license file. -
Test that Kong Enterprise is running:
Visit the Kong Manager at http://localhost:8002 (replace
localhost
with your server IP or hostname when running Kong on a remote system).
Troubleshooting
The Admin API only listens on the local interface by default. This was done as a
security enhancement. Note that we are overriding that in the above example with
KONG_ADMIN_LISTEN=0.0.0.0:8001
because Docker container networking benefits from
more open settings and enables Kong Manager and Dev Portal to talk with the Kong
Admin API.
Without a license properly referenced, you’ll get errors running migrations:
$ docker run -ti --rm ... kong migrations bootstrap
nginx: [alert] Error validating Kong license: license path environment variable not set
Also, without a license, you will get no output if you do a docker run
in
“daemon mode”—the -d
flag to docker run
:
$ docker run -d ... kong start
26a995171e23e37f89a4263a10bb084120ab0dbed1aa11a71c888c8e0d74a0b6
When you check the container, it won’t be running. Doing a docker logs
will
show you:
$ docker logs <container name>
nginx: [alert] Error validating Kong license: license path environment variable not set
As awareness, another error that can occur due to the vagaries of the interactions between text editors and copy & paste changing straight quotes (“ or ‘) into curly ones (“ or ” or ’ or ‘) is:
nginx: [alert] Error validating Kong license: could not decode license json
Your license data must contain only straight quotes to be considered valid JSON.