Development — Zebrafish Facility Manager

These pages set up a machine to work on ZFM, and keep it working, in two parts. Set up the machine ends with the code built and the services the code needs in place. Dev facilities starts from there: you give a facility a database full of real records, put it on the air at a local address, and bring it forward as the code changes under it. A third group, Working on the code, covers what you do once a facility is serving: the tests, the scripts, the release.

These pages get a development machine running one way, the way it has been done here. An experienced developer will see other ways to do some of it, and may prefer them: Node 24 installed system-wide instead of under a version manager, for one. That is fine. What following the pages as written gives you is a path that has been walked, where each step was checked against the one before it.

The deployment guide takes ZFM from a checkout to researchers signing in on a production host, and these pages follow it page for page, because a development machine is a production host with five differences:

production host	development machine
the database server is a managed service	the database server is a container on this machine
mail goes out through a mail provider	mail goes to a catcher on this machine, which delivers nothing
settings live in /etc/zfm	settings live in a gitignored directory inside the checkout
each facility is pointed at one of several installed releases	every facility runs the working tree, and there is one of it
the servers run as system services under the zfm account	the servers run as your own user's services, and are rebuilt as their source changes

What is the same is the web server. A development facility is served by Caddy at an address of its own, the way a production facility is, so the client's address logic is exercised as it ships.

Two facilities appear as examples throughout these pages: zri, the Zebrafish Research Institute, and udemo, the University of Demonstrations. Neither exists. Where a page shows one of them, the value for a real facility goes in its place.

Terms

Every page uses these words in the sense given here:

facility	a zebrafish research facility: some number of fish tanks, some number of principal investigators, and the researchers who work with them. In ZFM a server, a web address and a database are dedicated to each facility.
dev facility	a facility on this machine, built from a copy of a real facility's records, that you work in while developing.
the checkout	the clone of the repository on this machine, at the path ZFM_ROOT_DIR names.
the working tree	the code in the checkout as it is right now, which is the release every dev facility runs.
production host	the computer that runs the live system for real facilities. Dev facilities are built from copies of its records.
platform owner	your own account in every facility; the software calls the role super.
the admin db password	the password of the container's root account, which creates databases and the accounts that use them.
a facility's own database account	the account a facility's server connects with, which can reach that facility's database and no other.

Angle brackets are placeholders. <facility> is a dev facility's short name, <port> a number, and so on. Replace them, brackets and all.