Sign up| Login| Support

Updated Tutorial: How to deploy an NGINX API gateway on Heroku

Control Access, Monitor Traffic & Manage your API with 3scale

At 3scale, we recommend using NGINX as an API proxy for several reasons, including its outstanding performance and extensibility, thanks to the Lua scripting support. When used with the 3scale API Management Platform, it’s hands-down the best way to add an access control layer to your existing API.

The following tutorial describes the required steps to deploy NGINX as an API gateway on the Heroku platform. Heroku provides a fantastic, fully managed platform as a service for your application, so the required maintenance effort on your part will be minimal. Since NGINX is so lightweight, the free offering from Heroku will be enough for most cases.

High-level overview

We’ll create a Heroku application with a custom buildpack, including Lua and LuaRocks, and deploy the OpenResty distribution of NGINX using a rock especially tailored for Heroku. We will then use the NGINX configuration files generated by 3scale from your API dashboard, and we’ll tweak them to work properly with NGINX on Heroku.

What you’ll need


We’re going to…

  1. Set up your API in 3scale and download the auto-generated NGINX config files
  2. Clone the Git repository with template files
  3. Create an empty Heroku app
  4. Copy your 3scale NGINX config files into your project directory to replace the templates
  5. Modify the NGINX config files to adapt them for deploying in Heroku
  6. Push the Git repository to deploy NGINX on Heroku
  7. Check that everything works

Step-by-step tutorial

If you already have an API you can use that. Otherwise you should now jump to the “Deploying a sample API to Heroku” section of this tutorial, where you’ll deploy a test API in minutes.

Once you have an API to use with the proxy, you can carry on from here.

We’ll need to deploy the OpenResty web app server, which essentially is a bundle of the standard NGINX core with almost all the necessary 3rd party NGINX modules built in.

For an easy start, you can fork and clone the repository at

git clone

This repository contains some boilerplate files required by Heroku. Later on, you will only need to modify the nginx.sample.conf and nginx_3scale_access.lua. You will see a package.rockspec file is included. This is a special type of file that defines Lua dependencies and makes sure that the declared dependencies are fetched and installed when we push our repository to the server. There is only one dependency in this case, which is OpenResty.

After cloning the repository change into the directory that was just automatically created, named “api-proxy-3scale-heroku”.

Heroku doesn’t support the Lua runtime by default, so we’ll need to create the application using a custom buildpack that includes:

  • Lua 5.1
  • LuaRocks, a Lua package manager

You just need to execute this:

heroku create --buildpack

The output of this command will show an URL similar to this one:

This is where you’ll be able to reach your NGINX API proxy.

Heroku create command output

Now we have created an empty Lua application in Heroku. Before deploying NGINX with our configuration, we need to replace the nginx.sample.conf and nginx_3scale_access.lua with our own NGINX configuration files, which we’ll download from 3scale.

Go through the following steps to download your customized configuration files:

  1. Sign in to your 3scale account
  2. Go to the API section
  3. Select the service (which will be named “API” if you only have one)
  4. Select the Integration subsection in the sidebar

Once there, make sure the deployment option is set to on-premise gateway. Otherwise click on edit integration settings and select that deployment option.

Select the on-premise deployment option


There will be some fields that you’ll have to fill in with information about your API. This data will be used to automatically generate configuration files for NGINX, already customized to integrate your API with 3scale.

The most important field right now is the one at the top: “Private Base URL”. Here you should type the complete URL of your API service, complete with port. For instance:

If you need further guidance on how to fill the rest of these fields, visit this tutorial.

After you’ve completed all the fields, click on the “Test” button at the bottom right side of the page.


API integration screen


Now you’re ready to download the NGINX configuration for your API by scrolling down and clicking on “Download Nginx config”.

Download Nginx configuration

A few changes are required to the files you just downloaded.

  1. Move them into your “api-proxy-3scale-heroku” directory.
  2. Delete the existing nginx.conf and nginx_3scale_access.lua files
  3. Rename your new .conf file, downloaded from 3scale, to nginx.conf
  4. Do the same for your new .lua file, renaming it to nginx_3scale_access.lua
  5. Set your API provider key as an environment variable: heroku config:set THREESCALE_PROVIDER_KEY=1239832745abcde
  6. Modify nginx.conf
    1. Add to the top of the file the following lines:
      daemon off;
      error_log stderr;
    2. Replace listen 80; at the beginning of the server block for listen ${{PORT}};. This is necessary since Heroku can change the port where our process is listening. This way it will be filled in from a environment variable.
    3. On the next line, change the servername to be the hostname of your Heroku app for the NGINX proxy like in the example above;
    4. Replace access_by_lua_file lua_tmp.lua
      for access_by_lua_file nginx_3scale_access.lua
    5. On the two lines beginning set $provider_key replace them with
      set $provider_key "${{THREESCALE_PROVIDER_KEY}}";

Now we’re all set and ready to deploy your customized NGINX. Commit the changes, and push them to Heroku:

git commit -am "deploying proxy with custom configuration from 3scale"
git push heroku master


Now we have NGINX adding an access control layer on top of our API. We’ll make sure it’s working properly by making an authenticated request to your API.

Go back to the 3scale admin portal and get the credentials of one of the sample applications which you created when you first logged in to your 3scale account (if you missed that step, just create a developer account and an application within that account).

If your API endpoint is:

To use the API proxy, you should now make a request to the following URL:

Deploying a sample API to Heroku

To test your API proxy, you’ll need an API backend. Here we’ll walk you through the steps of deploying an API in Heroku. For this tutorial, we’ve picked the Sentiment API, which is an API that returns the sentiment rating of a given word. Bear in mind that you need to create an additional Heroku application to host this API. You cannot have NGINX and the API in the same Heroku application.

The basic endpoint of this API is:


The previous request would return:


We have already prepared a repository containing the Sentiment API and the required configuration files to deploy it in Heroku. You can find this repository here:

If you prefer to deploy your own API onto Heroku, the way you should prepare it depends on your programming language of choice. You can find all the information at the Heroku Dev Center.

To deploy the Sentiment API on Heroku, follow these steps:

  1. Clone the repository into your computer git clone
  2. Move into the repository directory that was created in your computer with the name “sentiment-api-heroku”
  3. Run heroku create (The console output will show a URL. This will be your API domain.)
  4. Run git push heroku master

To test that the API was deployed successfully, you can make a request like the following one to the URL that was generated after executing heroku create:

Of course, this is completely bypassing the access control layer! Note that once your API gateway is in place, you’ll want to make sure that public access to your API is blocked. For this purpose, you can define your own “proxy secret token” in your 3scale Integration Proxy wizard, under Advanced settings. Then your backend app simply verifies that the shared secret is correct.


If there is any problem after deploying to Heroku, it’s always useful to check the production logs. You can do so by running the following command:

heroku logs

During debugging, it might be useful to temporarily lower the level for error logging. You just need to edit the line that was added at the top of the nginx.conf file and append the desired level (all the possible options are described here):
error_log stderr info;

For further help, we strongly recommend you to check the Heroku Dev Center.


Full credit goes to Taylor Brown for proposing this solution as an alternative to deploying NGINX on Amazon EC2. Check it out here.

Also many thanks to Leaf Corcoran, creator of the Lua buildpack for Heroku and the awesome OpenResty LuaRocks.