This documentation explains how to use Paketo buildpacks to build applications that run web servers like HTTPD and NGINX. These docs focus on explaining common user workflows. For more in-depth description of the buildpacks’ behavior and configuration, see the reference documentation for each web server buildpack.
This documentation explains how to use the Paketo HTTPD Buildpack to build applications for several common use-cases. For more in-depth description of the buildpack’s behavior and configuration see the Paketo HTTPD Buildpack Reference documentation.
To build a sample app locally with this CNB using the pack CLI, run
git clone https://github.com/paketo-buildpacks/samples cd samples/httpd pack build my-app --buildpack paketo-buildpacks/httpd \ --builder paketobuildpacks/builder-jammy-full
See samples for how to run the app.
The HTTPD CNB (Cloud Native Buildpack) allows you to specify a version of the
Apache HTTP Server to use during deployment. This version can be specified
through the BP_HTTPD_VERSION environment variable. When specifying a version
of the Apache HTTP Server, you must choose a version that is available within the
buildpack. The supported versions can be found here
Specifying a version of httpd is not required. In the case that it is not
specified, the buildpack will provide the default version listed in the release
notes.
To configure the buildpack to use HTTPD v2.4.46 when deploying your app, set the
following environment variable at build time, either directly (ex. pack build my-app --env BP_HTTPD_VERSION=2.4.*) or through a
project.toml
file:
BP_HTTPD_VERSION="2.4.46"
Specifying the HTTP Server version through buildpack.yml configuration will
be deprecated in Apache HTTP Server Buildpack v1.0.0. To migrate from using
buildpack.yml please set the $BP_HTTPD_VERSION environment variable.
httpd.conf
The Apache HTTPD Server Buildpack supports building static
applications that do not include an httpd.conf. When the BP_WEB_SERVER
environment variable is set to httpd, the buildpack will generate an
http.conf during the build process.
BP_WEB_SERVER=httpd
It is possible to configure the generated httpd.conf in several ways. Each
option is configurable with an environment variable or service binding, as seen
below.
The BP_WEB_SERVER_ROOT variable allows you to
modify the location of the static files served by the web server. Its default
value is /workspace/public. 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
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
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
You are able to provide basic authentication credentials via a service
binding of type htpasswd that specifies the contents of a
.htpasswd file. The service binding should have the following directory
structure:
binding
└── type
└── .htpasswd
Include an httpd.conf file in your application’s source code or set
BP_WEB_SERVER=httpd in the build environment to automatically generate one.
The HTTPD Paketo buildpack will install the Apache HTTP Server binary and
configure it to start when the app image launches.
This documentation explains how to use the Paketo NGINX Buildpack to build applications for several common use-cases. For more in-depth description of the buildpack’s behavior and configuration see the Paketo NGINX Buildpack Reference documentation.
To build a sample app locally with this CNB using the pack CLI, run
git clone https://github.com/paketo-buildpacks/samples cd samples/nginx pack build my-app --buildpack paketo-buildpacks/nginx \ --builder paketobuildpacks/builder-jammy-base
See samples for how to run the app.
NOTE: Though the example above uses the Paketo Base builder, this buildpack is also compatible with the Paketo Full builder.
The NGINX CNB (Cloud Native Buildpack) allows you to specify a version of NGINX to use during
deployment. This version can be specified in a number of ways, including
through buildpack.yml. 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 the default version listed in the release
notes.
To configure the buildpack to use NGINX v1.19.8 when deploying your app, set the
following environment variable at build time, either directly (ex. pack build my-app --env BP_NGINX_VERSION=1.19.8) or through a
project.toml
file:
BP_NGINX_VERSION="1.19.8"
Specifying the NGINX version through buildpack.yml configuration will be
deprecated in NGINX Server Buildpack v1.0.0. To migrate from using
buildpack.yml please set the $BP_NGINX_VERSION environment variable.
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
It is possible to configure the generated nginx.conf in several ways. Each
option is configurable with an environment variable or service binding, as seen
below.
The BP_WEB_SERVER_ROOT variable allows you to
modify the location of the static files served by the web server. Its default
value is /workspace/public. 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
In auto-generated nginx.conf, the
server.location
directive is set to the catch-all or default location block. You can override
this by setting the BP_WEB_SERVER_LOCATION_PATH variable.
BP_WEB_SERVER_LOCATION_PATH="/custom"
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
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
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
The info will be made available at the path /stub_status at the specified
port. Make sure that this port isn’t used anywhere else in your application.
BP_NGINX_STUB_STATUS_PORT=8083
You are able to provide basic authentication credentials via a service
binding of type htpasswd that specifies the contents of a
.htpasswd file. The service binding should have the following directory
structure:
binding
└── type
└── .htpasswd
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 Paketo buildpack will install the NGINX binary and configure it to
start when the app image launches.
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 web-servers/nginx-sample
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 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 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 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"}}
NGINX requires that the dynamic module be built against the exact version of NGINX that your’re targeting, and be built on the same arch/platform. See this NGINX blog post on how to compile third-party dynamic modules.
See the NGINX
docs for more
information about how to set up an nginx.conf file.
The Paketo Web Servers buildpack combines buildpacks for Node.js with buildpacks for Apache HTTP Server and NGINX. As a result, it can build JavaScript source code into production-ready static assets, then automatically configure a web server to serve those assets. Check the Paketo samples repository for an example React app with build instructions.
Define a script under the "scripts" property of your package.json that
builds your production-ready static assets. Most frameworks bootstrap this
automatically. For React, it’s "build".
Find out where static assets are stored after the build script runs. It’ll
be a directory under the root of the app directory. For React, this is
./build by default.
Select which web server to use: NGINX or HTTPD.
[NGINX] If you chose HTTPD, skip to step 5. Use environment
variables to configure the server. BP_NODE_RUN_SCRIPTS should be set to
the name of the build script from step 1. BP_WEB_SERVER_ROOT should be
set to the build output directory from step 2. To (optionally) further
adjust the behaviour of the NGINX server, see the NGINX How-to
guides.
pack build frontend-app --buildpack paketo-buildpacks/web-servers \
--env BP_NODE_RUN_SCRIPTS=build \
--env BP_WEB_SERVER=nginx \
--env BP_WEB_SERVER_ROOT=build
BP_NODE_RUN_SCRIPTS should be set to
the name of the build script from step 1. BP_WEB_SERVER_ROOT should be
set to the build output directory from step 2. To (optionally) further
adjust the behaviour of the HTTPD server, see the HTTPD How-to
guides.pack build frontend-app --buildpack paketo-buildpacks/web-servers \
--env BP_NODE_RUN_SCRIPTS=build \
--env BP_WEB_SERVER=httpd \
--env BP_WEB_SERVER_ROOT=build
docker run --tty --env PORT=8080 --publish 8080:8080 frontend-app
DEBUG logging
Users of the Web Servers buildpack can access extra debug logs during the image build process by setting the BP_LOG_LEVEL
environment variable to DEBUG at build time. Additional debug logs will
appear in build logs if the relevant buildpacks have debug log lines.
pack build my-app --buildpack paketo-buildpacks/web-servers \ --env BP_LOG_LEVEL=DEBUG
Last modified: April 3, 2024