by Igor-Vuk


Heroku Buildpack: NGINX

Nginx-buildpack vendors NGINX inside a dyno and connects NGINX to an app server via UNIX domain sockets.


Some application servers (e.g. Ruby's Unicorn) halt progress when dealing with network I/O. Heroku's Cedar routing stack buffers only the headers of inbound requests. (The Cedar router will buffer the headers and body of a response up to 1MB) Thus, the Heroku router engages the dyno during the entire body transfer –from the client to dyno. For applications servers with blocking I/O, the latency per request will be degraded by the content transfer. By using NGINX in front of the application server, we can eliminate a great deal of transfer time from the application server. In addition to making request body transfers more efficient, all other I/O should be improved since the application server need only communicate with a UNIX socket on localhost. Basically, for webservers that are not designed for efficient, non-blocking I/O, we will benefit from having NGINX to handle all I/O operations.


  • Buildpack Version: 1.0
  • NGINX Version: 1.14.0


  • Your webserver listens to the socket at /tmp/nginx.socket.
  • You touch /tmp/app-initialized when you are ready for traffic.
  • You can start your web server with a shell command.


  • Unified NXNG/App Server logs.
  • L2met friendly NGINX log format.
  • Heroku request ids embedded in NGINX logs.
  • Crashes dyno if NGINX or App server crashes. Safety first.
  • Language/App Server agnostic.
  • Customizable NGINX config.
  • Application coordinated dyno starts.


NGINX will output the following style of logs:

measure.nginx.service=0.007 request_id=e2c79e86b3260b9c703756ec93f8a66d

You can correlate this id with your Heroku router logs:

at=info method=GET path=/ request_id=e2c79e86b3260b9c703756ec93f8a66d fwd="" dyno=web.1 connect=1ms service=8ms status=200 bytes=21

Language/App Server Agnostic

Nginx-buildpack provides a command named bin/start-nginx this command takes another command as an argument. You must pass your app server's startup command to start-nginx.

For example, to get NGINX and Unicorn up and running:

$ cat Procfile
web: bin/start-nginx bundle exec unicorn -c config/unicorn.rb

Setting the Worker Processes

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

Customizable NGINX Config

You can provide your own NGINX config by creating a file named nginx.conf.erb in the config directory of your app. Start by copying the buildpack's default config file.

Customizable NGINX Compile Options

See scripts/build_nginx for the build steps. Configuring is as easy as changing the "./configure" options.

You can run the builds in a Docker container:

$ docker-machine create --driver virtualbox cedar
$ eval "$(docker-machine env ceder)"
$ make build # It outputs the latest builds to bin/cedar-*

To test the builds:

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

Application/Dyno coordination

The buildpack will not start NGINX until a file has been written to /tmp/app-initialized. Since NGINX binds to the dyno's $PORT and since the $PORT determines if the app can receive traffic, you can delay NGINX accepting traffic until your application is ready to handle it. The examples below show how/when you should write the file when working with Unicorn.


Here are 2 setup examples. One example for a new app, another for an existing app. In both cases, we are working with ruby & unicorn. Keep in mind that this buildpack is not ruby specific.

Existing App

Update Buildpacks

$ heroku buildpacks:add

Update Procfile:

web: bin/start-nginx bundle exec unicorn -c config/unicorn.rb
$ git add Procfile
$ git commit -m 'Update procfile for NGINX buildpack'

Update Unicorn Config

require 'fileutils'
listen '/tmp/nginx.socket'
before_fork do |server,worker|
$ git add config/unicorn.rb
$ git commit -m 'Update unicorn config to listen on NGINX socket.'

Deploy Changes

$ git push heroku master

New App

$ mkdir myapp; cd myapp
$ git init


source ''
gem 'unicorn'

run {[200,{'Content-Type' => 'text/plain'}, ["hello world"]]}


require 'fileutils'
preload_app true
timeout 5
worker_processes 4
listen '/tmp/nginx.socket', backlog: 1024

before_fork do |server,worker|

Install Gems

$ bundle install

Create Procfile

web: bin/start-nginx bundle exec unicorn -c config/unicorn.rb

Create & Push Heroku App:

$ heroku create
$ heroku buildpacks:add heroku/ruby
$ heroku buildpacks:add
$ git add .
$ git commit -am "init"
$ git push heroku master
$ heroku logs -t

Visit App

$ heroku open

Bundling On Windows 10

1.) We will use Docker toolbox and Virtual Box. If we are one Windows other then Windows Home we will have Hyper V enabled. We need to turn it off and restart the computer to use toolobox. 2.) We start Docker Quickstart terminal and we go to the Nginx buildpack folder, folder wher eis our buildpack project.. 3.) To list all docker machines we run docker-machine ls

  • to stop the machine docker-machine stop <name>
  • to remove machine docker-machine rm <name> (leave the default one) *list all containers docker ps -a *list all running containers docker ps *stop all containers docker stop $(docker ps -a -q) *remove all containers docker rm $(docker ps -a -q) 4.) If there is no cedar curently running (we can also see that inside Virtual box, there is the default one and cedar) we run docker-machine create --driver virtualbox cedar 5.) After that we run docker-machine env cedar. 6.) On the last line it will says "Run this command to configure your shell". We just copy and run it. 7.) We make all the changes that we want inside buildpack. 8.) After that we run make build. This will output the latest build to bin folder 9.) We add it, commit it and push it to repo.

Deploying to Heroku When we update buildpack there are still cached files in heroku CACHE_DIR. We should clean them before deploying new buildpack. We run: 1.) heroku plugins:install heroku-repo This is just the first time to instal plugin for CLI. How to add, remove, list and update this CLI plugins we can see here. 2.) heroku repo:purge_cache -a <appname>

Note: Changes in the buildpack Changing Nginx version For Heroku-18 stach we change it inside Makefile. For other stacks we change it inside build_nginx file. This is the default version. Adding Modules We add it inside ./configure. Add it at the end. Important thing is that all lines end with \ except the last line. This modules will be build on Heroku dyno. That is why when we deploy to Heroku with Nginx we first deploy web: scripts/ inside of Procfile. That is when he will build and instal nginx inside of bin folder. We can see it by running heroku run bash

If we are on windows make build maybe will not work. We should follow this instructions to enable it. 1.) Go to ezwinports, 2.) Download (get the version without guile) 3.) Extract zip 4.) Copy the contents to C:\ProgramFiles\Git\mingw64\ merging the folders, but do NOT overwrite/replace any exisiting files. Basically we just copy and paste all the folders without overwriteing and they will merge.

Upgrading Heroku to the latest heroku-18 stack

Just be carefull to use heroku-18 where it says heroku-16.