PermalinkInstall Kong Gateway on Docker

PermalinkIntroduction

This guide walks through downloading, installing, and starting Kong Gateway on Docker.

The configuration shown in this guide is intended as an example. Depending on your environment, you may need to make modifications and take measures to properly conclude the installation and configuration.

Kong Gateway supports both PostgreSQL 9.5+ and Cassandra 3.11.* as its datastore. This guide provides steps to configure PostgreSQL.

This software is governed by the Kong Software License Agreement.

PermalinkDeployment options

The following instructions assume that you are deploying Kong Gateway in classic embedded mode.

If you want to run Kong Gateway in Hybrid mode, the instructions in this topic will walk you though setting up a Control Plane instance. Afterward, you will need to bring up additional gateway instances for the Data Planes, and perform further configuration steps. See Hybrid Mode Setup for details.

PermalinkPrerequisites

To complete this installation you will need a Docker-enabled system with proper Docker access.

PermalinkStep 1. Pull the Kong Gateway Docker image

Pull the following Docker image:

$ docker pull kong/kong-gateway:2.3.3.2-alpine

Note: Some older Kong Gateway images are not publicly accessible. If you need a specific patch version and can't find it on Kong's public Docker Hub page, contact Kong Support.

You should now have your Kong Gateway image locally.

Verify that it worked, and find the image ID matching your repository:

$ 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.

PermalinkStep 2. Create a Docker network

Create a custom network to allow the containers to discover and communicate with each other.

$ docker network create kong-ee-net

PermalinkStep 3. Start a database

Start a PostgreSQL container:

$ 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" \
  postgres:9.6

PermalinkStep 4. Prepare the Kong database

$ docker run --rm --network=kong-ee-net \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=kong-ee-database" \
  -e "KONG_PG_PASSWORD=kong" \
  -e "KONG_PASSWORD=<SOMETHING-YOU-KNOW>" \
  kong-ee kong migrations bootstrap

Note: For KONG_PASSWORD, replace <SOMETHING-YOU-KNOW> with a valid password that only you know.

PermalinkStep 5. Start the gateway with Kong Manager

$ docker run -d --name kong-ee --network=kong-ee-net \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=kong-ee-database" \
  -e "KONG_PG_PASSWORD=kong" \
  -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_ADMIN_GUI_URL=http://<DNSorIP>:8002" \
  -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

Note: For KONG_ADMIN_GUI_URL, replace <DNSorIP> with with the DNS name or IP of the Docker host. KONG_ADMIN_GUI_URL should have a protocol, for example, http://.

PermalinkStep 6. Verify your installation

Access the /services endpoint using the Admin API:
```
 $ curl -i -X GET --url http://<DNSorIP>:8001/services
```
You should receive an HTTP/1.1 200 OK message.
Verify that Kong Manager is running by accessing it using the URL specified in KONG_ADMIN_GUI_URL in Step 5:
```
 http://<DNSorIP>:8002
```

PermalinkStep 7. (Optional) Enable the Dev Portal

This feature is only available with a Kong Konnect Enterprise subscription.

Deploy a license.
In your container, set the Portal URL and set KONG_PORTAL to on:
```
 $ echo "KONG_PORTAL_GUI_HOST=localhost:8003 KONG_PORTAL=on kong reload exit" \
   | docker exec -i kong-ee /bin/sh
```
Note: For KONG_PORTAL_GUI_HOST, replace <DNSorIP> with with the DNS name or IP of the Docker host. The DNS or IP address for KONG_PORTAL_GUI_HOST should not be preceded by a protocol, for example, http://.

Execute the following command. Change <DNSorIP> to the IP or valid DNS of your Docker host:

 $ curl -X PATCH http://<DNSorIP>:8001/workspaces/default \
   --data "config.portal=true"

Access the Dev Portal for the default workspace using the URL specified in the KONG_PORTAL_GUI_HOST variable:
```
 http://<DNSorIP>:8003/default
```

PermalinkTroubleshooting

If you did not receive an HTTP/1.1 200 OK message or need assistance completing setup, reach out to your Support contact or head over to the Support Portal.

PermalinkNext Steps

Check out Kong Gateway’s series of Getting Started guides to get the most out of Kong Gateway.

If you have an Enterprise subscription, add the license using the /licenses Admin API endpoint.