Resources for Developers

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.

Set up this buildpack

This buildpack is designed to be used in conjunction with one or more additional buildpacks, thanks to the multi buildpack.

For instance, using 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: simple 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.8.0

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: nginx.org/en/docs to get details about how to configure your app.

Output

The application deployment output will look like:

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

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