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.4.1.0-alpine

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.

Tag the image.

docker tag kong/kong-gateway:2.4.1.0-alpine kong-ee

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={PASSWORD}" \
  kong-ee kong migrations bootstrap

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://localhost: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

The hostname for KONG_PORTAL_GUI_HOST must be preceded by a protocol, for example, http://.

PermalinkStep 6. Verify your installation

Access the /services endpoint using the Admin API:
```
 curl -i -X GET --url http://localhost:8001/services
```
You should receive a 200 status code.
Verify that Kong Manager is running by accessing it using the URL specified in KONG_ADMIN_GUI_URL in Step 5:
```
 http://localhost: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
```
The HOSTNAME for KONG_PORTAL_GUI_HOST should not be preceded by a protocol, for example, http://.

Execute the following command.

 curl -X PATCH --url http://localhost: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://localhost:8003/default
```

PermalinkTroubleshooting

If you did not receive a 200 OK status code 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.