Installing Kong Enterprise Docker Image
Introduction
A guide to installing Kong Enterprise—and its license file—using Docker.
Kong Gateway requires a license to run.
If you have lost access to your license.json
file but still have a valid
license for Kong Gateway (Enterprise), open a
support case to request the file.
Download and Install Kong Gateway
-
To install Kong Gateway versions 1.3.x and earlier, open a support case to request a Docker image. Kong Support will walk you through downloading the image.
-
Once you have the image, look it up locally:
$ docker images
-
Tag the image ID for easier use:
$ docker tag <IMAGE_ID> kong-ee
Note: Replace
<IMAGE_ID>
with the one matching your repository. -
Run the migrations with an ephemeral Kong container.—PostgreSQL 9.5 is required:
docker run -d --name kong-ee-database \ -p 5432:5432 \ -e "POSTGRES_USER=kong" \ -e "POSTGRES_DB=kong" \ -e "POSTGRES_PASSWORD=kong" \ -e "POSTGRES_HOST_AUTH_METHOD=trust" \ postgres:9.5
-
To make the license data easier to handle, export it as a shell variable. Please note that your license contents will differ!
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}}'
-
Run Kong migrations:
docker run --rm --link kong-ee-database:kong-ee-database \ -e "KONG_DATABASE=postgres" -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 up
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. -
Start Kong:
docker run -d --name kong-ee --link kong-ee-database:kong-ee-database \ -e "KONG_DATABASE=postgres" \ -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_PORTAL_GUI_PROTOCOL=http" \ -e "KONG_PORTAL_GUI_HOST=127.0.0.1:8003" \ -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. -
Kong Enterprise should now be installed and running. Test it by visiting Kong Manager at http://localhost:8002 (replace
localhost
with your server IP or hostname when running Kong on a remote system), or by visiting the Default Dev Portal at http://127.0.0.1:8003/default
FAQs
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 up
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.