Install Kong Gateway on Debian

    • A with root or root-equivalent access.
    • The following tools are installed:
    • (Enterprise only) A file from Kong.

    Download and install

    You can install Kong Gateway by downloading an installation package or using our APT repository.

    Package

    APT repository

    Install Kong Gateway on Debian from the command line.

    1. Install the package:

      Kong Gateway

      Kong Gateway (OSS)

      1. sudo dpkg -i kong-enterprise-edition-3.0.1.0.all.deb
      1. sudo dpkg -i kong-3.0.1.amd64.deb

    Kong Gateway

    Kong Gateway (OSS)

    Install the APT repository from the command line.

    1. Download the Kong APT repository:

      1. echo "deb [trusted=yes] https://download.konghq.com/gateway-3.x-debian-$(lsb_release -sc)/ \
      2. default all" | sudo tee /etc/apt/sources.list.d/kong.list
    2. Update the repository:

      1. sudo apt-get update
    3. Install Kong:

      Kong Gateway

      Kong Gateway (OSS)

      1. apt install -y kong-enterprise-edition=3.0.1.0

    Set up configs

    Kong Gateway comes with a default configuration property file that can be found at /etc/kong/kong.conf.default if you installed Kong Gateway with one of the official packages. This configuration file is used for setting Kong Gateway’s configuration properties at startup.

    To alter the default properties listed in the kong.conf.default file and configure Kong Gateway, make a copy of the file, rename it (for example kong.conf), make your updates, and save it to the same location.

    First, configure Kong Gateway using the kong.conf configuration file so it can connect to your database. See the data store section of the for all relevant configuration parameters.

    The following instructions use PostgreSQL as a database to store Kong configuration.

    We don’t recommend using Cassandra with Kong Gateway, because support for Cassandra is .

    1. Provision a database and a user before starting Kong Gateway:

      1. CREATE USER kong WITH PASSWORD 'super_secret'; CREATE DATABASE kong OWNER kong;
    2. Run the Kong Gateway migrations using the following command:

      1. kong migrations bootstrap -c {PATH_TO_KONG.CONF_FILE}

    If you want to store the configuration properties for all of Kong Gateway’s configured entities in a yaml declarative configuration file, also referred to as DB-less mode, you must create a kong.yml file and update the kong.conf configuration file to include the file path to the kong.yml file.

    First, the following command will generate a declarative configuration file in your current folder:

    1. kong config init

    The generated kong.yml file contains instructions for how to configure Kong Gateway using the file.

    Second, you must configure Kong Gateway using the kong.conf configuration file so it is aware of your declarative configuration file.

    Set the database option to off and the declarative_config option to the path of your kong.yml file as in the following example:

    1. database = off
    2. declarative_config = {PATH_TO_KONG.CONF_FILE}

    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, using the following command:

    1. KONG_PASSWORD={PASSWORD} kong migrations bootstrap -c {PATH_TO_KONG.CONF_FILE}

    Start Kong Gateway

    For more information, see .

    Start Kong Gateway using the following command:

    1. kong start -c {PATH_TO_KONG.CONF_FILE}

    Verify install

    If everything went well, you should see a message (Kong started) informing you that Kong Gateway is running.

    You can also check using the Admin API:

    By default, listens on the following ports:

    • :8443: Port on which listens for incoming HTTPS traffic. This port has similar behavior as the :8000 port, except that it expects HTTPS traffic only. This port can be disabled with the kong.confconfiguration file.
    • :8001: Port on which the Admin API used to configure listens.
    • : Port on which the Admin API listens for HTTPS traffic.

    The following steps are all optional and depend on the choices you want to make for your environment.

    If you have an Enterprise license for Kong Gateway, apply it using one of the methods below, depending on your environment.

    With a database

    Without a database

    Apply the license using the Admin API. The license data must contain straight quotes to be considered valid JSON (' and ", not or ).

    POST the contents of the provided license.json license to your Kong Gateway instance:

    cURL

    HTTPie

    1. curl -i -X POST http://localhost:8001/licenses \
    2. -d payload='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}'
    1. http POST :8001/licenses \
    2. payload='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}'

    Securely copy the license.json file to your home directory on the filesystem where you have installed Kong Gateway:

    1. $ scp license.json <system_username>@<server>:~

    Then, copy the license file again, this time to the /etc/kong directory:

    1. $ scp license.json /etc/kong/license.json

    Kong Gateway will look for a valid license in this location.

    If you’re running Kong Gateway with a database (either in traditional or hybrid mode), you can enable Kong Gateway’s graphical user interface (GUI), Kong Manager. See the Kong Manager setup guide for more information.

    If you’re running Kong Gateway with a database (either in traditional or hybrid mode), you can enable the Dev Portal

    1. Enable the Dev Portal in the kong.conf file by setting the portal property to on and the portal_gui_host property to the DNS or IP address of the system. For example:

      1. portal = on
      2. portal_gui_host = localhost:8003
    2. Restart Kong Gateway for the setting to take effect, using the following command:

      1. kong restart -c {PATH_TO_KONG.CONF_FILE}
    3. To enable the Dev Portal for a workspace, execute the following command, updating DNSorIP to reflect the IP or valid DNS for the system:

    4. Access the Dev Portal for the default workspace using the following URL, substituting your own DNS or IP:

      1. http://localhost:8003/default

    Troubleshooting and support

    For troubleshooting license issues, see:

    Next steps

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