Open-Source API Management and Microservice Management

Careful! You are browsing documentation for an outdated version of Kong Enterprise. Go here to browse the documentation for the latest version.

Estimated reading time: 6 minutes

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.

 $ 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 your license.json file into C:\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

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.