Build the installation artifact

On the build and test host you turn a checkout of the source into the installation artifact.

The installation artifact

The installation artifact is four directories:

zf-server/dist/	the compiled server, and the operator scripts beside it in dist/scripts/
node_modules/	every module the server needs in order to run, in one directory at the top of the installation artifact
zf-react-client/dist/	one web client that serves every facility
usage-guide/	the usage guide its users read, served by every facility at /usage-guide/ on its own address

Pick what you are shipping

Build from the commit you intend to ship, not from whatever your working tree happens to hold:

git fetch --tags
git checkout <tag>          # or the commit you mean
git status                  # expect a clean tree

The server and the web client each bake their own identity in during the build, from git describe --tags --always --dirty, and report it afterwards on GET /health and GET /facility-settings. Two consequences: the build has to happen in a git checkout with its tags fetched, and a dirty tree produces an installation artifact that says so for the rest of its life. Which tag to use, and what the digits mean, is Versioning and release in the development-practices site.

If the checkout you work in cannot be clean — somebody else's edits are in it, or your own work is part way through — build from a worktree at the commit you are shipping:

git worktree add /tmp/zfm-build <tag>   # or the commit you mean
cd /tmp/zfm-build

That directory holds the commit and nothing else, so the build bakes in the version you asked for and the checkout you work in is left as it is. Run the rest of this page there. It starts with no node_modules, which the next step installs. When the artifact is packaged, remove it:

git worktree remove /tmp/zfm-build

Build

scripts/check-modules.mjs || npm ci   # installs only if node_modules differs from the lock file
npm run build               # shared, then the server
cd zf-react-client && npm run export:web && cd ..
docs/build.sh zf-usage      # the usage guide

The usage guide is built with the documentation toolchain, which is set up once on this host as Deploying the docs says.

Am I ready to move on?

The best way we can think of is to run the tests!

cd zf-server && npm test && cd ..
cd zf-react-client && npm test && cd ..

The server suite runs against the MySQL 8 this host was prepared with, building a throwaway schema per worker and dropping it at the end. It reads no facility settings and sends no mail, so nothing it does depends on a facility existing. The client suite renders the screens in Node and needs nothing but the checkout. A failure in either is a reason not to package this commit.

Package it

scripts/package-artifact.sh

The script writes /tmp/zfm-<version>.tar.gz, a checksum beside it, and prints both paths and the size. Before packing anything it loads the assembled server, so a build that emitted less than the whole program is refused here rather than discovered on a host. It reads the checkout and changes nothing in it, so a machine you also develop on keeps the node_modules you work in.

The modules in it come from the lock file, with the development packages and the client's packages left out: no source, no compilers, no test runner. That is about 390 MB of files, which pack into a tarball of about 70 MB — one file to send to a host, and one checksum to prove it arrived whole.

An installation artifact runs on the operating system and processor it was assembled on. The mail library carries the one piece of compiled code in the set, and it ships as a prebuilt binary per platform, so a tarball built on x86-64 Linux installs on x86-64 Linux.

What this page does not build

The phone and tablet clients. Those are EAS builds, submitted to the app stores on their own schedule, and nothing in a facility deployment waits for them.