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

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