Deployment — Zebrafish Facility Manager

The Zebrafish Facility Manager — ZFM — is the stock book for a fish facility: the researchers, the genomic features they work with, the stocks that carry them, and the tanks those stocks live in. One deployment can serve several independent zebrafish facilities.

These pages take ZFM from a checkout to researchers signing in, in two parts. Deployment ends with a release on a host, inert: you prepare the hosts, build the thing that gets installed, and install it. Facility provisioning starts from a release that is already there: you give a facility its settings and its database, put it on the air, and later move it to a newer release. The two are done by different people on different days as often as not, and nothing in the second part needs the build host.

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, typically at a university: 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.
production host	a computer that runs the live system for real facilities.
build host	a computer on which you test the source code and build an installation artifact from it.
development host	a computer on which ZFM itself is written and tested.
installation artifact	the one file you install on a production host.
system-wide settings	the settings shared by every facility on the host. The mail account, for example.
server-side settings	the settings a facility uses to start up. Its port, for example.
GUI-side settings	the settings that can be adjusted at run time. Label printing options, for example.
/etc/zfm	home for the system-wide settings and each facility's server-side settings.
platform owner	your own account in every facility; the software calls the role super.
facility administrator	somebody at the facility who manages its users and its GUI-side settings.
database administrator	the database account that creates databases and the accounts that use them.
a facility's own database account	the account a facility's server runs with: it holds every privilege over that facility's own database and over the copy taken before its schema is changed, and none at all over any other facility's.

Angle brackets are placeholders. <facility> is a facility's short name, <db-name> the name of its database, <port> a number you choose — replace them, brackets and all.

One computer can do more than one of these jobs. A development machine usually does all three: the code is written there, the installation artifact is built there, and a practice facility is served there. Each job has its own settings, so these pages say which kind of host an instruction is for rather than which computer to sit at.

Know which of the two database accounts a command uses. The administrator's account creates a database and the account that uses it, and is needed for nothing after that. Everything else — the records a facility reads and writes, the migrations that change its schema, the copy taken before they run — is done with that facility's own account, which can reach no other facility's records.

Open items

• Deploy the documentation sites — mkdocs build + Caddy static serving: usage public at /best-practices, operator/installation docs on an unadvertised private subdomain. Wiring deferred until the docs are consolidated.
• Reference-data seeding — mutation_types and screen_types, two lookup tables a facility picks values from, are filled in by no step in this guide. Deferred pending a decision on whether a facility may add to that data.
• migration:baseline helper + pre-baseline schema-drift check — see the cutover on Migrate customer.