It is possible to build and run static, React, and Next.js webapps using the webapp build and webapp run subcommands.
To make it easier to build once and deploy into different environments and with different configuration,
compilation and static page generation are separated in the webapp build and webapp run steps.
This offers much more flexibility than standard Next.js build methods, since any environment variables accessed
via process.env, whether for pages or for API, will have values drawn from their runtime deployment environment,
not their build environment.
Webapp images are built using a wrapper: a recipe that pairs a base container image with a
containerfile that knows how to build the app source into a servable image. By default the
wrapper is auto-detected from the app source, and a specific wrapper can be selected with
--wrapper, e.g. stack webapp build --wrapper nextjs --source-repo ~/my-app. The available
wrappers can be listed with stack webapp wrappers.
See wrappers.md for how wrappers work, how they are discovered, how to use them in a stack, and how to author new ones.
Building usually requires no additional configuration. By default, the Next.js version specified in package.json
is used, and either yarn or npm will be used automatically depending on which lock files are present. These
can be overidden with the build arguments STACK_NEXTJS_VERSION and STACK_BUILD_TOOL respectively. For example: --extra-build-args "--build-arg STACK_NEXTJS_VERSION=13.4.12"
Example:
$ cd ~/work
$ git clone https://github.com/bozemanpass/test-progressive-web-app
$ stack webapp build --source-repo ~/work/test-progressive-web-app
...
Built host container for ~/bozemanpass/test-progressive-web-app with tag:
bozemanpass/test-progressive-web-app:stack
To test locally run:
stack webapp run --image bozemanpass/test-progressive-web-app:stack --config-file /path/to/environment.env
With webapp run a new container will be launched on the local machine, with runtime configuration provided by --config-file (if specified) and published on an available port. Multiple instances can be launched with different configuration.
Example:
# Production env
$ stack webapp run --image bozemanpass/test-progressive-web-app:stack --config-file /path/to/environment/production.env
Image: bozemanpass/test-progressive-web-app:stack
ID: 4c6e893bf436b3e91a2b92ce37e30e499685131705700bd92a90d2eb14eefd05
URL: http://localhost:32768
# Dev env
$ stack webapp run --image bozemanpass/test-progressive-web-app:stack --config-file /path/to/environment/dev.env
Image: bozemanpass/test-progressive-web-app:stack
ID: 9ab96494f563aafb6c057d88df58f9eca81b90f8721a4e068493a289a976051c
URL: http://localhost:32769
Use the subcommand webapp deploy to make a deployment directory that can be subsequently deployed to a Kubernetes cluster.
Example commands are shown below, assuming that the webapp container image bozemanpass/test-progressive-web-app:stack has already been built:
$ stack webapp deploy --kube-config ~/kubectl/k8s-kubeconfig.yaml --image-registry registry.digitalocean.com/laconic-registry --deployment-dir ~/bozemanpass/webapp-k8s-deployment --image bozemanpass/test-progressive-web-app:stack --url https://test-pwa-app.bpi.servesthe.world --config-file test-webapp.env
$ stack manage --dir ~/bozemanpass/webapp-k8s-deployment push-images
$ stack manage --dir ~/bozemanpass/webapp-k8s-deployment start