Looking for a reverse proxy or an API gateway for your apps? This buildpack might be the solution you are looking for. You first need to create a new Scalingo application and configure it to make use of the Nginx buildpack.

Purpose of This Buildpack

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=https://github.com/Scalingo/nginx-buildpack.git

Configuration

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
• servers.conf.erb: (optional) lets you configure your Nginx instance at the http level if required

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

You can also use the Nginx playground to help you write and debug your configuration file.

Specify Nginx Version

Nginx maintains two branches:

• One named Mainline, with an odd version number, which gets new features, updates and bugfixes;
• One named Stable, with an even version number, which only gets major bugfixes.

Maintenance of a version automatically ends when a new Stable or Mainline version begins.

By default, we’re installing the latest Stable 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:

Discouraged Directives

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

Configuration Examples

Use Nginx configuration: nginx.org/en/docs to get details about how to configure your app.

Split traffic to 2 APIs

This configuration example lets you split the traffic to two different Scalingo applications depending on the path:

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

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

You need to define the two environment variables API_V1_BACKEND and API_V2_BACKEND with the domain name of the applications. For instance:

scalingo env-set API_V1_BACKEND=https://my-app-1.osc-fr1.scalingo.io
scalingo env-set API_V2_BACKEND=https://my-app-2.osc-fr1.scalingo.io

This configuration must be written in the nginx.conf.erb file at the root of your application.

Setup throttling with a limit_req_zone

This configuration example lets you throttle the traffic to a Scalingo application:

# instruction at the http level like
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

server {
    server_name localhost;
    listen <%= ENV['PORT'] %>;
    charset utf-8;
    location / {
        limit_req zone=one burst=5;
        proxy_pass http://<%= ENV["API_V1_BACKEND"] %>;
    }
}

This configuration must be written in the servers.conf.erb file at the root of your application.

Output

The application deployment output will look like:

-----> Cloning custom buildpack: https://github.com/Scalingo/nginx-buildpack.git#master
-----> Bundling NGINX 1.10.1