by heroku

GitHub Readme.md

Heroku Buildpack for Kong

Deploy Kong 0.14 Community Edition as a Heroku app.

🔬👩‍💻 This software is a community proof-of-concept: MIT license


Deploy the heroku-kong app to get started.


Potentially breaking changes are documented in UPGRADING.


While it's possible to use this buildpack directly, you'll be giving up quite a few features of the heroku-kong app:

  • Admin API will not be automatically proxied for secure external access
  • Admin Console via heroku run will require manual setup
  • local development is not preconfigured

Create a new git repo and Heroku app:

APP_NAME=my-kong-gateway # name this something unique for your app
mkdir $APP_NAME
git init
heroku create $APP_NAME
heroku buildpacks:set https://github.com/heroku/heroku-buildpack-kong.git
heroku addons:create heroku-postgresql:hobby-dev

Create the file config/kong.conf.etlua based on the sample config file. This is a config template which generates config/kong.conf at runtime.

git add config/kong.conf.etlua

echo '# Kong Proxy' > README.md
git add README.md

git commit -m '🐒'
git push heroku master

🚀 Check heroku logs and heroku open to verify Kong launches.

Plugins & other Lua source

  • Kong plugins
  • Lua rocks
    • specify in the app's Rockfile
    • each line is {NAME} {VERSION}
  • Other Lua source modules
    • lib/{NAME}.lua or
    • lib/{NAME}/init.lua

Environment variables

  • PORT exposed on the app/dyno
    • set automatically by the Heroku dyno manager
  • Kong itself may be configured with KONG_ prefixed variables
  • Heroku build configuration:
    • These variables only effect new deployments.
    • KONG_RUNTIME_ARCHIVE_URL location of pre-compiled Kong runtime archive
    • Setting these will lengthen build-time, usually 4-8 minutes for compilation from source. By default, this buildpack downloads pre-compiled, cached Kong binaries to accelerate deployment time. (More details available in DEV.)
    • KONG_GIT_URL git repo URL for Kong source
      • default: https://github.com/kong/kong.git
    • KONG_GIT_COMMITISH git branch/tag/commit for Kong source
      • default: master

Using Environment Variables in Plugins

To use env vars within your own code.

  1. Whitelist the variable name for use within Nginx
    • In a custom Nginx config file add env MY_VARIABLE;
    • See: Nginx config (below)
  2. Access the variable in Lua plugins
    • Use os.getenv('MY_VARIABLE') to retrieve the value.

Nginx config

Kong is an Nginx-based application. To customize the underlying Nginx configuration, commit the file config/nginx.template with contents based on the docs or this included sample.

Pre-release script

This buildpack installs a release phase script to automatically run Kong's database migrations for each deployment.

Apps can define a custom pre-release script which will be automatically invoked before the built-in release phase script.

Simply commit your executable script to the app's repo as bin/prerelease, and then that script will be run for every release. The release will fail if the script exits with non-zero status.


This buildpack supports Heroku CI to automate test runs and integrate with deployment workflow.

Tests should follow the Kong plugin testing guide.

App requirements:

  • spec/kong_tests.conf must contain the Kong configuration for running tests

See: sample Heroku Kong app which contains a complete test suite.


We vendor the sources for Lua, LuaRocks, & OpenResty/Nginx and compile them with a writable /app/kong-runtime prefix. Attempts to bootstrap Kong on Heroku using existing Lua & apt buildpacks failed due to their compile-time prefixes of /usr/local which is read-only in a dyno.

OpenSSL 1.0.2 (required by OpenResty) is also compiled from source.


This buildpack normally downloads an archive of the pre-compiled Kong runtime, and so skips a very lengthy (~10-minute) build process. To skip that cache speed-up and compile it, set either KONG_GIT_URL or KONG_GIT_COMMITISH. To create a new archive, see DEV notes.

This buildpack caches its compilation artifacts from the sources in vendor/. Changes to the sources in vendor/ will be detected and the cache ignored.

If you need to trigger a full rebuild without changing the source, use the Heroku Repo CLI plugin to purge the cache:

heroku repo:purge_cache