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
tooff
, NGINX does not GZip files. - If you set
GZIP_DOWNLOADS
toon
, 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 tosyslog
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:
NGINX Buildpack Repository in GitHub: Find more information about using and extending the NGINX buildpack in the NGINX buildpack GitHub repository.
Release Notes: Find current information about this buildpack on the NGINX buildpack release page in GitHub.
Slack: Join the #buildpacks channel in the Cloud Foundry Slack community.