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 kong.conf its configuration properties and a kong.yml file for specifying the entities as a declarative configuration.

With a Database

  1. Install the dependencies

    OpenResty 1.15.8.1. Kong being an OpenResty application, you must follow the OpenResty installation instructions. You will need OpenSSL and PCRE to compile OpenResty, and to at least use the following compilation options:

     $ ./configure \
       --with-pcre-jit \
       --with-http_ssl_module \
       --with-http_realip_module \
       --with-http_stub_status_module \
       --with-http_v2_module
    

    You might have to specify --with-openssl and you can add any other option you’d like, such as additional Nginx modules or a custom --prefix directory.

    OpenResty conveniently bundles LuaJIT and resty-cli which are essential to Kong. Add the nginx and resty executables to your $PATH:

     $ export PATH="$PATH:/usr/local/openresty/bin"
    

    Luarocks 3.1.3, compiled with the LuaJIT version bundled with OpenResty (See the --with-lua and --with-lua-include configure options). Example:

     ./configure \
       --lua-suffix=jit \
       --with-lua=/usr/local/openresty/luajit \
       --with-lua-include=/usr/local/openresty/luajit/include/luajit-2.1
    
  2. Install Kong

    Now that OpenResty is installed, we can use Luarocks to install Kong’s Lua sources:

     $ luarocks install kong 1.3.0-0
    

    Or:

     $ git clone git@github.com:Kong/kong.git
     $ cd kong
     $ [sudo] make install # this simply runs the `luarocks make kong-*.rockspec` command
    

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

  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, download the kong.conf.default file and adjust it as necessary. Then, as root, add it to /etc:

     $ sudo mkdir -p /etc/kong
     $ sudo cp kong.conf.default /etc/kong/kong.conf
    
  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; CREATE DATABASE kong OWNER kong;
    

    Next, run the Kong migrations:

     $ kong migrations bootstrap [-c /path/to/kong.conf]
    

    Note for Kong < 0.15: with Kong versions below 0.15 (up to 0.14), use the up sub-command instead of bootstrap. Also note that with Kong < 0.15, migrations should never be run concurrently; only one Kong node should be performing migrations at a time. This limitation is lifted for Kong 0.15, 1.0, and above.

  5. Start Kong

     $ kong start [-c /path/to/kong.conf]
    
  6. Use Kong

    Verify that Kong is running:

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

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

Without a database

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

  2. Write 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]: /1.3.x/db-less-and-declarative-config/#the-declarative-configuration-format instructions while doing so.

     $ kong config init
    

    We’ll assume the file is named kong.yml.

  3. Add kong.conf

    Download kong.conf.default file and adjust it as necessary.

    In particular, make sure to set the database config option to off and the declarative_config option to the absolute path to kong.yml:

     database = off
     ...
     declarative_config = /path/to/kong.yml
    
    
  4. Start Kong

     $ kong start [-c /path/to/kong.conf]
    
  5. Use Kong

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

     $ curl -i http://localhost:8001/
    
Get Updates!

Follow Up:

Get future release notes emailed to you.


Having Trouble? We're Here to Help!