The NGINX buildpack provides the NGINX binary distribution.
The buildpack installs the NGINX binary distribution onto the $PATH which
makes it available for subsequent buildpacks and/or the application image.
The NGINX CNB provides nginx as a dependency. Downstream buildpacks, like PHP Web CNB can require the nginx dependency by generating a Build Plan TOML file that looks like the following:
[[requires]]
# The name of the NGINX dependency is "nginx". This value is considered
# part of the public API for the buildpack and will not change without a plan
# for deprecation.
name = "nginx"
# The version of the NGINX dependency is not required. In the case it
# is not specified, the buildpack will provide the default version, which can
# be seen in the buildpack.toml file.
# If you wish to request a specific version, the buildpack supports
# specifying a semver constraint in the form of "1.*", "1.17.*", or even
# "1.17.9".
version = "1.17.9"
# The NGINX buildpack supports some non-required metadata options.
[requires.metadata]
# Setting the launch flag to true will ensure that the NGINX
# dependency is available on the $PATH for the running application. If you are
# writing an application that needs to run NGINX at runtime, this flag should
# be set to true.
launch = trueTo package this buildpack for consumption:
$ ./scripts/package.sh
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.
A usage example can be found in the samples repository under the nginx
directory.
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
This is a generic case of the {{port}} directive described ealier. 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 enable or
disable 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
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 amodules/ngx_foo_module.sofile in your app directory and add the following to the top of yournginx.conffile:
{{module "ngx_foo_module"}}
- To load a buildpack-provided module like
ngx_stream_module, add the following to the top of yournginx.conffile. You do not need to provide anngx_stream_module.sofile:
{{module "ngx_stream_module"}}
Specifying the NGINX Server version through buildpack.yml configuration
is deprecated and will not be supported in NGINX Server Buildpack v1.0.0.
To migrate from using buildpack.yml please set the following environment
variables at build time either directly (ex. pack build my-app --env BP_ENVIRONMENT_VARIABLE=some-value) or through a project.toml
file
The BP_NGINX_VERSION variable allows you to specify the version of NGINX Server that is installed.
BP_NGINX_VERSION=1.21.0This will replace the following structure in buildpack.yml:
nginx:
# this allows you to specify a version constraint for the nginx dependency
# any valid semver constraints (e.g. 1.* and 1.21.*) are also acceptable
version: "1.21.0"The BP_WEB_SERVER_ENABLE_PUSH_STATE variable enables push state based routing for Single-page applications relying on browser history API.
NGINX Server will send the content at / in response to any requested endpoint.
Usefull for React, Angular, Vue and other SPAs.
The BP_NGINX_STUB_STATUS_PORT variable exposes a handful of NGINX Server metrics via the stub_status module which provides basic status information on provided port.
This comes handy for monitoring the server. For example using NGINX Prometheus Exporter
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent