PermalinkInstall Kong Gateway on Ubuntu
PermalinkIntroduction
This guide walks through downloading, installing, and starting Kong Gateway 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.
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 supported Ubuntu system with root-equivalent access.
PermalinkStep 1. Prepare to install Kong Gateway
Download the Debian package:
- Choose your Ubuntu version:
-
Select a Kong Gateway version from the list to download it.
Versions are listed in chronological order.
For example:
kong-enterprise-edition_2.4.1.0_all.deb
-
Copy the
.deb
file to your home directory on the Ubuntu system. For example:$ scp kong-enterprise-edition_2.4.1.0_all.deb <ubuntu_user>@<server>:~
PermalinkStep 2. Install Kong Gateway
-
Update APT:
$ sudo apt-get update
-
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
PermalinkStep 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 $ psql
-
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.
$ psql> \q $ exit
PermalinkStep 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. Replacepg_user
,pg_password
, andpg_database
with the values:pg_user = kong pg_password = kong pg_database = kong
PermalinkStep 5. Seed the Super Admin’s password and bootstrap Kong Gateway
root
, and the worker processes run as kong
by
default. If this is not the desired behavior, you can switch the Nginx master process to run on the built-in
kong
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.
PermalinkStep 6. Finalize your configuration and verify installation
PermalinkEnable 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 port8001
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
8002
.
Permalink(Optional) Enable the Dev Portal
-
Enable the Dev Portal by updating
/etc/kong/kong.conf
to set theportal
property toon
and theportal_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
-
Enable the Dev Portal for a workspace. 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"
-
Access the Dev Portal for the default workspace using the following URL, substituting your own DNS or IP:
http://<DNSorIP>:8003/default
PermalinkTroubleshooting
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
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.