Heroku Buildpack: Nginx

Nginx-buildpack installs & runs the Nginx web server inside a Heroku app.

• Presets for specific use-cases
  • Static sites
  • Local proxy to app servers
• Complete control of Nginx config in config/nginx.conf.erb
  • erb template supports dynamic config at start-up
  • see Nginx docs
• writes Heroku request ids & server timing to access logs

These are auto-selected based on the app's stack at build time.

With Nginx's flexibility, it can be configured & used for many different purposes. See the documentation for the mode you wish to use.

HTTP server for websites and single page apps. [docs]

HTTP proxy to an app server running in the same dyno, via UNIX domain sockets. [docs]

Proxy is the original buildpack mode that is enabled by default, if the config/nginx.conf.erb file is not added to app source.

This mode has been superceeded by Static mode.

Have a use for Nginx that does not fit one of the above presets?

Add this buildpack to an app, as the last buildpack:

heroku buildpacks:add --app APP_NAME heroku-community/nginx

…and then setup config/nginx.conf.erb & Procfile in the app's source repo.

You can configure Nginx's worker_processes directive via the NGINX_WORKERS environment variable.

For example, to set your NGINX_WORKERS to 8 on a PX dyno:

$ heroku config:set NGINX_WORKERS=8

Similarly, the NGINX_WORKER_CONNECTIONS environment variable can configure the worker_connections directive:

$ heroku config:set NGINX_WORKER_CONNECTIONS=2048

This requires a clone of this repository and Docker. All you need to do is have Docker setup and running on your machine. The Makefile will take care of the rest.

Configuring is as easy as changing the options passed to ./configure in scripts/build_nginx.

Run the builds in a container via:

$ make build

The binaries will be packed into tar files and placed in the repository's root directory. Commit the changes and push your repository.

Finally update your app to use your custom buildpack on Heroku either at https://dashboard.heroku.com/apps/#{YOUR_APP_NAME}/settings or via the Heroku CLI via:

heroku buildpacks:set #{YOUR_GIT_REPO_CLONE}

To test the builds locally:

$ make shell
$ cp bin/nginx-$STACK bin/nginx
$ FORCE=1 bin/start-nginx

Process docs for buildpack maintainers.

Please use only stable, even-numbered Nginx releases.

Revise the version variables in scripts/build_nginx, and then run the builds in a container (requires Docker) via:

$ make build

Then, commit & pull-request the resulting changes.

Ruby versions are downloaded from heroku-buildpack-ruby's distribution site. Only Heroku's supported Ruby versions are available.

Revise the ruby_version variable in bin/compile.

Then, commit & pull-request the resulting changes.