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.
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.
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.
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 : Use environment variables to configure the server.
BP_NODE_RUN_SCRIPTS
to the name of the build script from step 1.BP_WEB_SERVER_ROOT
to the build output directory from step 2.HTTPD : Use environment variables to configure the server.
BP_NODE_RUN_SCRIPTS
to build script from step 1.BP_WEB_SERVER_ROOT
to the build output directory from step 2.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.
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.
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:
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.
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.
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
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:
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.
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.