Estimated reading time:
This guide walks through downloading, installing, and starting Kong Gateway (Enterprise) on Ubuntu.
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 supports both PostgreSQL 9.5+ and Cassandra 3.11.* as its datastore. This guide provides
steps to configure PostgreSQL. For assistance in setting up Cassandra, please contact your Kong Sales or Support representative.
The following instructions assume that you are deploying Kong Gateway (Enterprise) in classic embedded mode.
If you want to run Kong Gateway (Enterprise) 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 Kong instances for the Data Planes, and perform further configuration steps. See Hybrid Mode Setup for details.
To complete this installation you will need:
- A valid Bintray account with access to the Kong repository. You receive access
when you begin a paid Kong Konnect subscription.
- You will need your username, account password, account API Key,
and Kong Konnect license file. For example:
- Bintray username:
- Bintray password:
- Bintray API key:
- To find the API Key, go to https://bintray.com/profile/edit and select API Key.
- To find the license JSON file, log into your Bintray
account and go to
For more details, see Accessing Your License.
- A supported Ubuntu system with root-equivalent access.
Step 1. Prepare to install Kong Gateway and download license file
Download the Debian package
- Log in to Bintray using your Kong credentials. See prerequisites
for information on how to get access.
- Go to: https://bintray.com/kong/kong-enterprise-edition-deb/ubuntu.
- Select the latest Kong version from the list. Kong Gateway (Enterprise) versions are listed in reverse chronological order.
- From the Kong version detail page, select the Files tab.
- Click the
.deb file matching your target Ubuntu OS version. For example, select
kong-enterprise-edition-18.104.22.168.bionic.all.deb for the Ubuntu Bionic Beaver release.
.deb file to your home directory on the Ubuntu system. For example:
$ scp kong-enterprise-edition-22.214.171.124.bionic.all.deb <ubuntu_user>@<server>:~
Download your enterprise license
Download your license file from your account files in Bintray:
Securely copy the license file to your home directory on the Ubuntu system:
$ scp license.json <ubuntu_username>@<server>:~
You should now have two files in your home directory on the target system:
- The Kong
.deb package file
- The license file
Step 2. Install Kong Gateway
Install Kong Gateway:
$ sudo apt-get install /absolute/path/to/package.deb
Note: Your version may be different based on when you obtained the package
Copy the license file to the
$ sudo cp license.json /etc/kong/license.json
Kong will look for a valid license in this location.
Step 3. Set up PostgreSQL
PostgreSQL is available in all Ubuntu versions by default. However, Ubuntu
snapshots a specific version of PostgreSQL that is then supported throughout the
lifetime of that Ubuntu version. Other versions of PostgreSQL are available
through the PostgreSQL apt repository.
Kong supports versions 9.5 and higher. Ensure the distribution of PostgreSQL
for your version of Ubuntu is a supported version for Kong. For more
information about PostgreSQL on Ubuntu, see https://www.postgresql.org/download/linux/ubuntu/.
Install PostgreSQL. This command may not work on all versions of Ubuntu.
$ sudo apt-get install postgresql postgresql-contrib
Switch to PostgreSQL user and launch PostgreSQL
$ sudo -i -u postgres
Create a Kong database with a username and password.
$ psql> CREATE USER kong; CREATE DATABASE kong OWNER kong; ALTER USER kong WITH password 'kong';
⚠️ Note: Make sure the username and password for the Kong Database are
kept safe. This example uses a simple username and password for illustrative purposes only. Note the database name, username and password for later.
Exit from PostgreSQL and return to your terminal account.
Step 4. Modify Kong Gateway’s configuration file
Make a copy of Kong Gateway’s default configuration file.
$ sudo cp /etc/kong/kong.conf.default /etc/kong/kong.conf
Uncomment and update the PostgreSQL database properties in
/etc/kong/kong.conf using your preferred text editor. Replace
pg_database with the values:
pg_user = kong
pg_password = kong
pg_database = kong
Step 5. Seed the Super Admin’s password and bootstrap Kong Gateway
When you start Kong, the Nginx master process runs
, and the worker processes run as
default. If this is not the desired behavior, you can switch the Nginx master process to run on the built-in
user or to a custom non-root user before starting Kong.
For more information, see
Running Kong as a Non-Root User
Setting a password for the Super Admin before initial start-up is strongly recommended. This will permit the use of RBAC (Role Based Access Control) at a later time, if needed.
Create an environment variable with the desired Super Admin password and store the password in a safe place. Run migrations to prepare the Kong database:
$ sudo KONG_PASSWORD=<password-only-you-know> /usr/local/bin/kong migrations bootstrap -c /etc/kong/kong.conf
Start Kong Gateway:
$ sudo /usr/local/bin/kong start -c /etc/kong/kong.conf
Verify Kong Gateway is working:
$ curl -i -X GET --url http://localhost:8001/services
You should receive a
HTTP/1.1 200 OK message.
Step 6. Finalize your configuration and verify installation
Enable and configure Kong Manager
To access the gateway’s Graphical User Interface, Kong Manager, update the
admin_gui_url property in
/etc/kong/kong.conf file the to the DNS or IP address of the system. For example:
admin_gui_url = http://<DNSorIP>:8002
This setting needs to resolve to a network path that will reach the host.
It is necessary to update the administration API setting to listen on the needed network interfaces on the host. A setting of
0.0.0.0:8001 will listen on port
8001 on all available network interfaces.
admin_listen = 0.0.0.0:8001, 0.0.0.0:8444 ssl
You may also list network interfaces separately as in this example:
admin_listen = 0.0.0.0:8001, 0.0.0.0:8444 ssl, 127.0.0.1:8001, 127.0.0.1:8444 ssl
Restart Kong for the setting to take effect:
$ sudo /usr/local/bin/kong restart
You may now access Kong Manager on port
Enable the Dev Portal
Enable the Dev Portal by updating
/etc/kong/kong.conf to set the
portal property to
on and the
portal_gui_host property to the DNS or IP address of the system. For example:
portal = on
portal_gui_host = <DNSorIP>:8003
Restart Kong Gateway for the setting to take effect:
$ sudo /usr/local/bin/kong restart
The final step is to enable the Developer Portal. To do this, execute the following command, updating
DNSorIP to reflect the IP or valid DNS for the system.
$ curl -X PATCH http://<DNSorIP>:8001/workspaces/default --data "config.portal=true"
You can now access the Developer Portal on the default workspace with a URL like:
If you did not receive an
HTTP/1.1 200 OK message or need assistance completing
your setup, reach out to your Kong Support contact or go to the
Check out Kong Gateway’s series of
Getting Started guides to get the most
out of Kong Gateway.