docs community blog github
Edit

How to Build Web Servers with Paketo Buildpacks

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.

HTTPD

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.

Build a Sample App

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:full
copy to clipboard
Copied!

See samples for how to run the app.

NOTE: The Paketo Full builder is required because HTTPD relies on operating system libraries only present in the Full builder.

Install a Specific HTTPD Version

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.

Using BP_HTTPD_VERSION

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"
copy to clipboard
Copied!

Deprecated: Using buildpack.yml

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.

Automatically Generate an 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
copy to clipboard
Copied!

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.

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
copy to clipboard
Copied!

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
copy to clipboard
Copied!

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
copy to clipboard
Copied!

Set Up Basic Authentication

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

Start an HTTPD Server at App Launch Time

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.

NGINX

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.

Build a Sample App

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:base
copy to clipboard
Copied!

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.

Install a Specific NGINX Version

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.

Using BP_NGINX_VERSION

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"
copy to clipboard
Copied!

Deprecated: Using buildpack.yml

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.

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
copy to clipboard
Copied!

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.

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
copy to clipboard
Copied!

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
copy to clipboard
Copied!

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
copy to clipboard
Copied!

Set Up Basic Authentication

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

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 Paketo 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.

A usage example can be found in the samples repository under the nginx directory.

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}};
}
copy to clipboard
Copied!

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

docker run --tty --env PORT=8080 --publish 8080:8080 my-nginx-image
copy to clipboard
Copied!

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 enable or disable gzipping of responses based on the value of GZIP_DOWNLOADS:

gzip {{env "GZIP_DOWNLOADS"}};
copy to clipboard
Copied!

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
copy to clipboard
Copied!

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"}}
copy to clipboard
Copied!

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"}}
copy to clipboard
Copied!

See the NGINX docs for more information about how to set up an nginx.conf file.

Build and Serve a Frontend Framework App

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.

  1. 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".

  2. 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.

  3. Select which web server to use: NGINX or HTTPD.

  4. [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-nginx --buildpack paketo-buildpacks/web-servers \
                          --env BP_NODE_RUN_SCRIPTS=build \
                          --env BP_WEB_SERVER=nginx \
                          --env BP_WEB_SERVER_ROOT=build
copy to clipboard
Copied!
  1. [HTTPD] If you chose NGINX, skip to step 6. 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 HTTPD server, see the HTTPD How-to guides.
pack build frontend-httpd --buildpack paketo-buildpacks/web-servers \
                          --env BP_NODE_RUN_SCRIPTS=build \
                          --env BP_WEB_SERVER=httpd \
                          --env BP_WEB_SERVER_ROOT=build
copy to clipboard
Copied!
  1. You’re done! The resulting app container will serve your frontend app with an automatically generated server configuration.
Edit

Last modified: May 12, 2022