This documentation explains how to use the Tanzu Web Servers buildpacks to build applications that run web servers like HTTPD and NGINX. You can use this builpack for applications that serve static conent, or build JavaScript source code into production-ready static assets, then automatically configure a web server to serve those assets.

These docs focus on explaining common user workflows. For more in-depth description of the buildpack's behavior and configuration, see the reference documentation for each web server buildpack.

Enabling the Web Servers Buildpack

The Tanzu Web Servers buildpack combines buildpacks in the Node.js family 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.

How to use in TAP

If you are using Web Servers Buildpack in TAP 1.2, please also see the section How to use in TAP 1.2

Check out the Paketo samples repository for an example React app that can be built by the Web Servers buildpack.

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

  5. [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 the HTTPD doc

  6. Install the “full” dependencies instead of the default "lite" dependencies by setting buildservice.descriptor_name to “full” in tap-values.yaml.

  7. Create a workload with the --param clusterBuilder=full which will utilize the full builder which has the webserver buildpack.

A typical workload.yaml for building the Paketo JavaScript frontend sample App in the default namespace looks like this:

---
apiVersion: carto.run/v1alpha1
kind: Workload
metadata:
  labels:
    app.kubernetes.io/part-of: javascript-frontend-sample
    apps.tanzu.vmware.com/has-tests: "true"
    apps.tanzu.vmware.com/workload-type: web
  name: javascript-frontend-sample
spec:
  build:
    env:
    - name: BP_NODE_RUN_SCRIPTS
      value: build
    - name: BP_WEB_SERVER
      value: nginx
    - name: BP_WEB_SERVER_ROOT
      value: build
    - name: BP_WEB_SERVER_ENABLE_PUSH_STATE
      value: "true"
  params:
  - name: clusterBuilder
    value: full
  source:
    git:
      ref:
        branch: main
      url: https://github.com/paketo-buildpacks/samples
    subPath: web-servers/javascript-frontend-sample

where metadata.name is the application name the workload is a part of, and spec.source.git points to the remote source code.

  1. You can then trigger an image build by running:
tanzu apps workload apply --file workload.yaml
  1. You're done! The resulting app container will serve your frontend app with an automatically generated server configuration.

How to use in TAP 1.2

In TAP 1.2, the full builder does not detect JavaScript frontent apps to be built by the Web Servers buildpack. In order to use the Web Servers buildpack in TAP 1.2, you need to create a Custom Builder on the full stack as follows:

  1. Create a builder order yaml file named builder-for-web-servers.yaml as follows:
- group:
  - id: tanzu-buildpacks/dotnet-core
- group:
  - id: tanzu-buildpacks/go
- group:
  - id: tanzu-buildpacks/python
- group:
  - id: tanzu-buildpacks/php
- group:
  - id: tanzu-buildpacks/web-servers
- group:
  - id: tanzu-buildpacks/java-native-image
- group:
  - id: tanzu-buildpacks/java
- group:
  - id: tanzu-buildpacks/nodejs
- group:
  - id: paketo-buildpacks/procfile

If you compare the order of the buildpacks in the above yaml with the order in the default full builder, the Web Servers buildpack appears before the Node.js buildpack here thereby allowing your app to be built as a Web Server app rather than just a Node.js app.

Sample order yaml files are available on the VMware Tanzu Build Service Dependencies page on Tanzu Network. For more info about the order definition, see builder.toml in the Cloud Native Buildpacks documentation.

  1. Use kp cli to create the builder

Assuming default namespace, you'll run:

kp clusterbuilder create builder-for-web-servers \
--tag REPO-LOCATION:IMAGE-TAG \
--order builder-for-web-servers.yaml \
--stack full \
--store default

where REPO-LOCATION:IMAGE-TAG is the the registry location where the builder is created. For more info please see the TBS documentation on creating builders.

  1. Now, you can apply your workload using a workload.yaml just like in the How to use in TAP section, with the only difference being the use of the newly created builder in the spec.params.
  params:
  - name: clusterBuilder
    value: builder-for-web-servers

How to use with pack

Check out the Paketo samples repository for an example React app with build instructions.

See the above section How to use in TAP on setting the right values for the BP_ env variables. You can also get more info on env variable configurations in the NGINX doc, HTTPD docs and Node.js docs

For NGINX, a typical build command looks like this:

pack build frontend-nginx --buildpack <tanzu-web-servers-buildpack> \
                          --env BP_NODE_RUN_SCRIPTS=build \
                          --env BP_WEB_SERVER=nginx \
                          --env BP_WEB_SERVER_ROOT=build

For HTTPD, a typical build command looks like this:

pack build frontend-httpd --buildpack <tanzu-web-servers-buildpack>\
                          --env BP_NODE_RUN_SCRIPTS=build \
                          --env BP_WEB_SERVER=httpd \
                          --env BP_WEB_SERVER_ROOT=build
  1. You're done! The resulting app container will serve your frontend app with an automatically generated server configuration.

How to use in TBS

Install the full descriptor and create an image using the full builder. Use kp image create to create an image resource. For more details, see Build Service Documentation

check-circle-line exclamation-circle-line close-line
Scroll to top icon