This topic tells you how to use the Tanzu NGINX Buildpack.

The Tanzu NGINX Buildpack supports the installation and running of the NGINX web server.

Specifying an NGINX Version

The NGINX Cloud Native Buildpack(CNB) allows you to specify a version of NGINX to use during deployment. This version can be specified via env variable BP_NGINX_VERSION. When specifying a version of the NGINX engine, you must choose a version that is available within the buildpack.

Specifying a version of nginx is not required. In the case that it is not specified, the buildpack will provide a default version.

Using BP_NGINX_VERSION

To configure the buildpack to use a specific NGINX version when deploying your app, set the following environment variable at build time, either directly by using, for example, pack build my-app --env BP_NGINX_VERSION=1.19.8, or through a project.toml file:

BP_NGINX_VERSION="1.19.8"

Automatically Generate an nginx.conf

The NGINX Buildpack supports building static applications that do not include an nginx.conf. When the BP_WEB_SERVER environment variable is set to nginx, the buildpack will generate an nginx.conf during the build process.

BP_WEB_SERVER=nginx

You can configure the generated nginx.conf in several ways. Each option is configurable with an environment variable or service binding, as seen below.

Set the Root Directory for Static Files

The BP_WEB_SERVER_ROOT variable allows you to modify the location of the static files served by the web server. Set the BP_WEB_SERVER_ROOT variable to an absolute file path or a file path relative to /workspace. For example, setting BP_WEB_SERVER_ROOT=my-build-directory changes the file path of served files to /workspace/my-build-directory.

BP_WEB_SERVER_ROOT=htdocs

Enable Push-State Routing

The BP_WEB_SERVER_ENABLE_PUSH_STATE variable enables push state routing functionality. This is useful for single-page web applications.

BP_WEB_SERVER_ENABLE_PUSH_STATE=true

Redirect HTTP Requests to HTTPS

The BP_WEB_SERVER_FORCE_HTTPS variable enables enforcing HTTPS for server connections. HTTP requests will be redirected to the corresponding HTTPS endpoint.

BP_WEB_SERVER_FORCE_HTTPS=true

Set Up Basic Authentication

You are able to provide basic authentication credentials by using a service bindings of type htpasswd that specifies the contents of a .htpasswd file. The service binding should have the following directory structure:

binding
└── type
└── .htpasswd

Start an NGINX Server at App Launch Time

Include an nginx.conf file in your application's source code or set BP_WEB_SERVER=nginx in the build environment to automatically generate one. The NGINX buildpack will install the NGINX binary and configure it to start when the app image launches.

Configure the NGINX Server with Launch-time Values

The NGINX buildpack supports data driven templates for nginx config. You can use templated variables like {{port}}, {{env "FOO"}} and {{module "ngx_stream_module"}} in your nginx.conf to use values known at launch time.

For an NGINX usage example, see the web-servers/nginx-sample/directory in the paketo-buildpacks GitHub repository.

PORT

Use {{port}} to dynamically set the port at which the server will accepts requests. At launch time, the buildpack will read the value of $PORT to set the value of {{port}}.

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

server {
  listen {{port}};
}

Then run the built image using the PORT variable set as follows:

docker run --tty --env PORT=8080 --publish 8080:8080 my-nginx-image

Environment Variables

This is a generic case of the {{port}} directive described earlier. To use the value of any environment variable $FOOVAR available at launch time, use the directive {{env "FOOVAR"}} in your nginx.conf.

For example, include the following in your nginx.conf file to activate or deactivate gzipping of responses based on the value of GZIP_DOWNLOADS:

gzip {{env "GZIP_DOWNLOADS"}};

Then run the built image using the GZIP_DOWNLOADS variable set as follows:

docker run --tty --env PORT=8080 --env GZIP_DOWNLOADS=off --publish 8080:8080 my-nginx-image

Use Dynamic Modules at App Launch Time

You can use templates to set the path to a dynamic module using the load_module directive.

To load a user-provided module named ngx_foo_module, provide a modules/ngx_foo_module.so file in your app directory and add the following to the top of your nginx.conf file:

{{module "ngx_foo_module"}}

To load a buildpack-provided 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"}}

For more information about how to set up an nginx.conf file, see the NGINX documentation

Behavior

When the NGINX Buildpack participates in a build, it will contribute in one of two ways:

  1. When an nginx.conf file is present in your app's source code, the buildpack will set up an NGINX server with that config.

  2. When the nginx.conf is not present in the app's source code, the buildpack simply provides the NGINX dependency to subsequent buildpacks without actually setting up a server.

  3. When the BP_WEB_SERVER is set to nginx, the buildpack will set up an NGINX server with a default configuration.

Environment Variable Configuration

  • BP_LIVE_RELOAD_ENABLED: Enables reloadable processes.

  • BP_NGINX_VERSION: Allows you to specify the version of the NGINX server that is installed.

  • BP_WEB_SERVER: When the value is set to nginx the buildpack will generate a default nginx.conf.

  • BP_WEB_SERVER_ROOT: Defaults to public, setting this allows you to modify the location of the static files served by the web server with either an absolute file path or a file path relative to /workspace.

  • BP_WEB_SERVER_ENABLE_PUSH_STATE: Enables push state routing functionality.

  • BP_WEB_SERVER_FORCE_HTTPS: Allows you to enforce HTTPS for server connections by redirecting all requests to use the HTTPS protocol.

Supported Service Bindings

The Nginx buildpack can be configured using service bindings.

type Required Files # Bindings of this Type Accepted
htpasswd type, .htpasswd 0 or 1
check-circle-line exclamation-circle-line close-line
Scroll to top icon