Nginx Buildpack for Custom Reverse Proxy

Purpose of This Buildpack

Looking for a reverse proxy or an API gateway for your apps? This buildpack might be the solution you are looking for. The Nginx buildpack lets you specify custom Nginx configuration. With this buildpack, you can provide a Nginx configuration file with the rules you want to set.

Setup This Buildpack

Configure your application to use the Nginx buildpack via the web dashboard or the Scalingo CLI:

$ scalingo create my-app
$ scalingo env-set BUILDPACK_URL=


The buildpack is expecting a configuration file at the root of the project which can be:

  • nginx.conf: configuration file
  • nginx.conf.erb: template to generate the configuration file

If the template is found, it will be rendered as configuration file, it let you use environment variables as in the following examples.

Specify Nginx Version

By default we’re installing the latest available version of Nginx, but if you want to use a specific version, you can define the environment variable NGINX_VERSION:

$ scalingo env-set NGINX_VERSION=1.14.2

Scalingo supports the following versions of Nginx:

  • 1.14.2
  • 1.15.8
  • 1.16.1
  • 1.17.6

Discouraged Directives

The following directives should not be used in you configuration file: listen, access_log, error_log and server_name.

Configuration Examples

Split traffic to 2 APIs

location /api/v1 {
  proxy_pass <%= ENV["API_V1_BACKEND"] %>;

location /api/v2 {
  proxy_pass <%= ENV["API_V2_BACKEND"] %>;

Use nginx configuration: to get details about how to configure your app.


The application deployment output will look like:

-----> Cloning custom buildpack:
-----> Bundling NGINX 1.10.1

Multiple Configuration Files

You may want to use multiple configuration files in your application. This is possible with the NGINX_INCLUDES environment variable:

scalingo --app my-app env-set NGINX_INCLUDES="./conf/nginx-1.conf ./conf/nginx-2.conf"

Advanced Informations

The configuration file you have to provide is at the server level, if you need to add something at the http level, please open an issue or a pull request and we’ll discuss it.

mode_edit Suggest edits