Table of Contents

Kong can run either with or without a database.

When using a database, you will use the kong.conf configuration file for setting Kong’s configuration properties at start-up, and the database as storage of all configured entities, such as the Routes and Services to which Kong proxies.

When not using a database, you will use environment variables, and a kong.yml file for specifying the entities as a declarative configuration.

With a Database

About the dependencies

Kong depends on several components (the versions mentioned are the preferred ones):

  1. OpenResty
  2. Nginx Patches
  3. OpenResty Patches
  4. Kong Nginx Module
  5. OpenSSL 1.1.1k
  6. PCRE 8.44
  7. LuaRocks 3.7.0
  8. LibYAML 0.2.5

It is not trivial to get everything built correctly, thus we provide kong-build-tools.

  1. Build the dependencies

    At first, you need to clone kong-build-tools:

    $ mkdir kong-sources
    $ cd kong-sources
    $ git clone

    Then you need to build the dependencies:

    $ ./kong-build-tools/openresty-build-tools/kong-ngx-build \
        --prefix deps \
        --work work \
        --openresty \
        --openssl 1.1.1k \
        --kong-nginx-module master \
        --luarocks 3.7.0 \
        --pcre 8.44 \
        --jobs 6 \

    Now, you should have the dependencies built, but before we continue, let’s export some environment variables:

    $ export OPENSSL_DIR=$(pwd)/deps/openssl
    $ export PATH=$(pwd)/deps/openresty/bin:$PATH
    $ export PATH=$(pwd)/deps/openresty/nginx/sbin:$PATH
    $ export PATH=$(pwd)/deps/openssl/bin:$PATH
    $ export PATH=$(pwd)/deps/luarocks/bin:$PATH

    Check everything is working:

    $ nginx -V
    $ resty -v
    $ openresty -V
    $ openssl version -a
    $ luarocks --version

    You will also need LibYAML 0.2.5 that you can install either manually or by using your operating system packages:

    1. Ubuntu: apt install libyaml-dev
    2. Fedora: dnf install libyaml-devel
    3. macOS: brew install libyaml

    At this point you may continue to the next step, but if you are interested in running Go plugins, please follow the Go guide.

  2. Install Kong

     $ git clone
     $ cd kong
     $ git checkout 2.5.1
     $ make install
     $ cd ..

    Finally, place the bin/kong script in your $PATH:

     $ export PATH=$(pwd)/kong/bin:$PATH

    Check everything is working:

     $ kong version --vv

    You can also install Kong with LuaRocks. but you will need to install the kong script manually:

     $ luarocks install kong 2.5.1-0
  3. Add kong.conf

    Note: This step is required if you are using Cassandra; it is optional for Postgres users.

    By default, Kong is configured to communicate with a local Postgres instance. If you are using Cassandra, or need to modify any settings, copy the default configuration file and adjust it as necessary.

     $ cp kong/kong.conf.default kong.conf
     $ <vim|nano|…> kong.conf

    You may also place the configuration file to /etc/kong where Kong can automatically detect it on start:

     $ [sudo] mkdir --parents /etc/kong
     $ [sudo] cp kong.conf /etc/kong
  4. Prepare your database

    Configure Kong so it can connect to your database. Kong supports both PostgreSQL 9.5+ and Cassandra 3.x.x as its datastore.

    If you are using Postgres, provision a database and a user before starting Kong:

     CREATE USER kong;

    Next, run the Kong migrations:

     $ kong migrations bootstrap [-conf kong.conf]
  5. Start Kong

     $ kong start --prefix node [--conf kong.conf]

    prefix is also optional or can be specified in kong.conf, but in the above example we decided to specify it for illustrative purposes.

  6. Use Kong

    Verify that Kong is running:

     $ curl --include http://localhost:8001/

    Quickly learn how to use Kong with the 5-minute Quickstart.

Without a database

  1. Follow steps 1 and 2 (Build the dependencies, Install Kong) from the list above.

  2. Write a declarative configuration file

    The following command will generate a kong.yml file in your current folder. It contains instructions about how to fill it up. Follow the [Declarative Configuration Format]: /gateway-oss/latest/db-less-and-declarative-config/#the-declarative-configuration-format instructions while doing so.

     $ kong config init
  3. Start Kong

    On database configuration steps above, we used kong.conf file for the configuration. Alternatively, you can use environment variables to configure Kong:

     $ KONG_DATABASE=off \
       kong start --prefix node
  4. Use Kong

    Verify that Kong is running, and it has the entities detailed in the declarative config file:

     $ curl --include http://localhost:8001/

Having Trouble? We're here to help!