Use the Tanzu Web Servers Buildpack

This topic tells you how to use the Tanzu Web Servers buildpacks to build applications that run web servers such as HTTPD and NGINX. You can use this buildpack for applications that serve static content, 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 Tanzu Application Platform

If you are using Web Servers Buildpack in Tanzu Application Platform 1.2, also see the section How to use in Tanzu Application Platform 1.2.

For an example React app that the Web Servers buildpack can build, see the Paketo samples repository.

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.

   NGINX : Use environment variables to configure the server.

   1. Set BP_NODE_RUN_SCRIPTS to the name of the build script from step 1.
   2. Set BP_WEB_SERVER_ROOT to the build output directory from step 2.
   3. (Optional) To further adjust the behavior of the NGINX server, see the Automatically Generate an nginx.conf section in the topic Using the Tanzu NGINX Buildpack.

   HTTPD : Use environment variables to configure the server.

   1. Set BP_NODE_RUN_SCRIPTS to build script from step 1.
   2. Set BP_WEB_SERVER_ROOT to the build output directory from step 2.
   3. (Optional) To further adjust the behavior of the HTTPD server, see the Automatically Generate an httpd.conf section in the topic Use the Tanzu HTTPD Buildpack.

4. Create a workload.yaml.

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

5. Trigger an image build by running:

   tanzu apps workload apply --file workload.yaml
   

You're done! The resulting app container will serve your frontend app with an automatically generated server configuration.

How to use in Tanzu Application Platform v1.2

In Tanzu Application Platform v1.2, the full builder does not detect JavaScript frontend apps to be built by the Web Servers buildpack. To use the Web Servers buildpack in Tanzu Application Platform v1.2, you must 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 preceding YAML with the order in the default full builder, the Web Servers buildpack appears before the Node.js buildpack here. This allows your app to be built as a Web Server app rather than a Node.js app.

   Sample order YAML files are available under VMware Tanzu Build Service Dependencies on the Broadcom Support Portal. For more information about the order definition, see the Cloud Native Buildpacks documentation.

2. Create the builder using the kp CLI. If you are using the default namespace, 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 information about creating builders, see the Tanzu Build Service documentation.

3. Apply your workload using a workload.yaml similar to the How to use in Tanzu Application Platform section, with the only difference being the use of the newly created builder in spec.params.

     params:
     - name: clusterBuilder
       value: builder-for-web-servers
   

How to use with pack

For an example React app with build instructions, see the Paketo samples repository.

For how to set the right values for the BP_* env variables, see How to use in Tanzu Application Platform earlier in this topic. You can also get more information about environment variable configurations in the Environment Variable Configuration section in the following sections:

• NGINX Environment Variable Configuration,
• HTTPD Environment Variable Configuration and
• Node.js Buildpack-Set Environment Variables

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

You're done! The resulting app container will serve your frontend app with an automatically generated server configuration.

How to use in Tanzu Build Service

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