NGINX Buildpack

Page last updated:

This topic describes how to push your NGINX app to Cloud Foundry and how to configure your NGINX app to use the NGINX buildpack.

Push an App

If your app contains an nginx.conf file, Cloud Foundry automatically uses the NGINX buildpack when you run cf push to deploy your app.

If your Cloud Foundry deployment does not have the NGINX buildpack installed or the installed version is outdated, run cf push YOUR-APP -b https://github.com/cloudfoundry/nginx-buildpack.git to deploy your app with the current buildpack. Replace YOUR-APP with the name of your app.

For example:

$ cf push my-app -b https://github.com/cloudfoundry/nginx-buildpack.git

Configure NGINX

Pivotal recommends that you use the default NGINX directory structure for your NGINX webserver. You can view this directory structure in the nginx-buildpack repository in GitHub.

The NGINX webserver setup includes the following:

  • A root folder for all static web content
  • A MIME type configuration file
  • An NGINX configuration file
  • A buildpack.yml YAML file that defines the version of NGINX to use. As an example, see buildpack.yml in the Cloud Foundry NGINX Buildpack repository in GitHub.

You should make any custom configuration changes based on these default files to ensure compatibility with the buildpack.

Create the nginx.conf File

Use the templating syntax when you create an nginx.conf file. This templating syntax loads modules and binds to ports based on values known at launch time.

Port

Use {{port}} to set the port to listen on. At launch time, {{port}} will interpolate in the value of $PORT.

Note: You must use {{port}} in your nginx.conf file.

For example, to set an NGINX server to listen on $PORT, include the following in your nginx.conf file:

server {
  listen {{port}};
}

Name Resolution

NGINX does not resolve internal routes by default. To resolve internal routes, use {{nameservers}} to set the resolver IP address. At launch time, {{nameservers}} interpolates the address of a platform-provided DNS service that includes information about internal routes.

Connections to internal routes do not go through the Cloud Foundry routing tier. As a result, you might see errors if you proxy an app on an internal route while it is restarting. There are some workarounds you might need to consider.

For more information, see Using DNS for Service Discovery with NGINX and NGINX Plus on the NGINX blog.

Environment Variables

To use an environment variable, include {{env "YOUR-VARIABLE"}}. Replace YOUR-VARIABLE with the name of an environment variable. At staging and at launch, the current value of the environment variable is retrieved.

For example, include the following in your nginx.conf file to enable or disable GZipping based on the value of GZIP_DOWNLOADS:

gzip {{env "GZIP_DOWNLOADS"}};
  • If you set GZIP_DOWNLOADS to off, NGINX does not GZip files.
  • If you set GZIP_DOWNLOADS to on, NGINX GZips files.

Unescaped Environment Variables

To use unescaped environment variables, add an array of environment variable names to the buildpack.yml. See the following example:

---
nginx:
  version: stable
  plaintext_env_vars:
    - "OVERRIDE"

In this example, the OVERRIDE environment variable can contain .json content without being html escaped. Ensure that you properly quote such variables to appear as strings in the nginx.conf file.

Loading Dynamic Modules

NGINX can dynamically load modules at runtime. These modules are shared-object files that can be dynamically loaded using the load_module directive. In addition to loading modules dynamically, the version of NGINX provided by the buildpack has statically compiled the following modules into the NGINX binary:

  • ngx_http_ssl_module
  • ngx_http_realip_module
  • ngx_http_gunzip_module
  • ngx_http_gzip_static_module
  • ngx_http_auth_request_module
  • ngx_http_random_index_module
  • ngx_http_secure_link_module
  • ngx_http_stub_status_module
  • ngx_http_sub_module

These statically compiled modules do not need to be loaded at runtime and are already available for use.

To load a dynamic NGINX module, use the following syntax in your app’s nginx.conf file:

{{module "MODULE-NAME"}}

If you have provided a module in a modules directory located at the root of your app, the buildpack instructs NGINX to load that module. If you have not provided a module, the buildpack instructs NGINX to search for a matching built-in dynamic module.

As of v0.0.5 of the buildpack, the ngx_stream_module is available as a dynamic module that is built into the buildpack.

For example, to load a custom module named ngx_hello_module, provide a modules/ngx_hello_module.so file in your app directory and add the following to the top of your nginx.conf file:

{{module "ngx_hello_module"}}

To load a built-in module like ngx_stream_module, add the following to the top of your nginx.conf file. You do not need to provide an ngx_stream_module.so file:

{{module "ngx_stream_module"}}

Note: To name your modules directory something other than modules, use the NGINX load_module directive, providing a path to the module relative to the location of your nginx.conf file. For example: load_module some_module_dir/my_module.so

Enabling Debugging

Debugging helps to identify a bug in the program code if something goes wrong. It is generally used in developing or testing third-party or experimental modules.

By default, debug logging will be disabled in the NGINX buildpack, which helps optimize performance. The user will need to set the debug level with the error_log directive in the nginx.conf to enable debug logging.

To use the debug logging, add the error_log entry to your nginx.conf file, following the syntax below:

Syntax: error_log file [level];

  • The first parameter defines a file that will store the log. The special value stderr selects the standard error file. Logging to syslog can be configured by specifying the “syslog:” prefix.

  • The second parameter determines the level of logging, and can be one of the following:

    • debug
    • info
    • notice
    • warn
    • error
    • crit
    • alert
    • emerg

Note: Log levels above are listed in the order of increasing severity. Setting a certain log level will cause all messages of the specified and more severe log levels to be logged. For example, the default level error will cause error, crit, alert, and emerg messages to be logged. If this parameter is omitted then error is used.

Example:

error_log /path/to/log debug;

Debugging Logs for Selected Clients

It is also possible to enable the debugging log for selected client addresses only:

error_log /path/to/log;

events {
debug_connection 192.168.1.1;
debug_connection 192.168.10.0/24;
}

Logging to a cyclic memory buffer

The debugging log can be written to a cyclic memory buffer:

error_log memory:32m debug;

Logging to the memory buffer on the debug level does not have significant impact on performance even under high load. In this case, the log can be extracted using a gdb script like the following one:

set $log = ngx_cycle->log

while $log->writer != ngx_log_memory_writer
set $log = $log->next
end

set $buf = (ngx_log_memory_buf_t *) $log->wdata
dump binary memory debug_log.txt $buf->start $buf->end

Buildpack Support

The following resources can assist you when using the NGINX buildpack or when developing your own NGINX buildpack: