Skip to content

Serve a facility

This page sets up a running system for a single facility. You need to:

  • start a server dedicated to the facility
  • create a web address for the people who work there
  • edit the facility's GUI-side settings

Prerequisites

Done already, on the pages before this one:

  • the host is prepared, and ZFM is installed on it
  • the facility has its server-side settings in /etc/zfm/<facility>.env
  • the facility's database holds the current set of tables and the platform owner's account
  • the facility's web address finds this host

The web address is the one written in the facility's settings. Ask this machine what the name resolves to:

getent hosts <facility>.<domain-name>

The address it prints has to be one of this host's. A public address has to resolve before the facility is served, because the certificate for it is issued to whoever answers at that name. A facility on a private network resolves only on the machines you have told, and telling them comes later on this page.

Every command on this page uses these names:
RELEASE the release this facility is to run, in /srv/zfm/releases on this host
FACILITY the facility's short name, such as zri — the name of its settings file, of its service, and of its subdomain

Set them before you start:

export RELEASE=/srv/zfm/releases/<version>
export FACILITY=<facility>

Starting a server dedicated to the facility

Every facility on the host runs a server of its own. All of them run the same program, and each reads its own settings from /etc/zfm/zfm.conf and /etc/zfm/<facility>.env, which we set up earlier.

systemd runs those servers. It starts a facility's server when the machine boots, restarts the server if it dies, and keeps everything the server prints, which is where you read what happened.

First say which release this facility runs. A facility is pointed at one release of its own, and both of its halves follow that pointer: the server systemd starts, and the web client its address serves. Nothing else decides it — so a facility comes back on the release it is pointed at after a crash or a reboot, and two facilities on this host can be on different releases.

sudo install -d -m 755 /srv/zfm/facilities/$FACILITY
sudo ln -sfn $RELEASE /srv/zfm/facilities/$FACILITY/current

Then ask systemd to start and manage the facility's server:

sudo systemctl enable --now zfm-server@$FACILITY

Am I ready to move on?

systemctl is-enabled zfm-server@$FACILITY  # enabled
systemctl status zfm-server@$FACILITY      # active (running)
curl -s localhost:<port>/health            # {"status":"ok","facility":"<facility>","version":"..."}

readlink /srv/zfm/facilities/$FACILITY/current   # the release it runs

is-enabled is about the next reboot, status about now. The port is the one in the facility's settings, and the facility that comes back from /health proves the server read the settings you think it did. When a server is not running, sudo journalctl -u zfm-server@$FACILITY -n 50 says why.

Creating a web address for the facility

The people at a facility reach it at a dedicated web address — zri.example.org.

The following script sets up a web address for a facility using Caddy. It makes use of the facility's server-side configuration at /etc/zfm/<facility>.env to set up the url for the facility's web address, and the port its server answers on.

# VIEW the generated caddy config without installing:
sudo env FACILITY=$FACILITY node $RELEASE/zf-server/dist/scripts/render-caddy-site.js

# INSTALL generated caddy config
sudo env FACILITY=$FACILITY node $RELEASE/zf-server/dist/scripts/render-caddy-site.js --install

The script validates before installing. It reports errors like an invalid URL or problems reading server-side config files. It also checks the configuration before putting it to work, so that a fault shows up here rather than later: Caddy refuses a configuration it cannot accept and carries on with the one it had, which leaves every other facility serving normally and your new facility simply absent.

Under the covers, the configuration tells Caddy to serve the web client at that address, and to pass the client's requests for data to this facility's server on its own port.

Whether the address is served with a certificate was decided when the facility's URL was written. An https:// URL gets one, fetched and renewed for you, and is served on ports 80 and 443. An http:// URL gets none, and is served on port 80 alone.

Am I ready to move on?

The facility's web address is the one written in its settings:

grep FACILITY_URL /etc/zfm/$FACILITY.env

Open that address in a browser. ZFM's sign-in screen is the answer.

A facility on a private network has a name that nothing resolves, so the machine running the browser needs to be told where to find it. Add the host's address on that network to its hosts file:

<the host's address on that network> <facility>.test

Editing the facility's GUI-side settings

What the facility is called on screen, which features it uses, how its tank labels are laid out, what its password rules are: these say what the facility is like to work in rather than what its server needs, so they are a record in the facility's own database. The record is written the first time the facility's server runs, and most of it can be changed only by the platform owner: the branding, the security policy, the label layout, the outside services a facility consults. What the facility's own administrator can change later is its name and abbreviation, a short list of feature toggles, and the label measurements. A change is in force as soon as it is saved.

Sign in as the platform owner, at the facility's web address:

https://<facility>.<domain-name>/login

Then work through those screens with the customer. Each setting is described where it is edited.

Am I ready to move on?

Reload the facility in the browser. What you set is what the screens show, because the record is read as the screens are drawn rather than when the server starts.