Skip to content

Build a dev facility

This page builds one dev facility on this machine: its database, filled from a copy of a real facility's records and brought up to the working tree's schema; its own database account; and its settings. It serves nothing at the end, and it can be built again from scratch at any time, which is the point.

Real records are the only input that finds real problems, so a dev facility is not seeded from fixtures. It is a real facility's dump, carried through the same migration a customer's records go through at cutover. Every rebuild is a rehearsal of that, and a mapping that breaks on real data breaks here rather than at a customer.

Prerequisites

  • The machine is set up, from First time setup: the containers are up, the shared settings are written, and ZFM_CONFIG_DIR points at the checkout's settings directory.
  • The production host accepts your ssh key as do1, from Prerequisites, and the key is in your agent. ssh-add once if ssh do1 hostname asks for a passphrase.

What to decide first

A dev facility is a production facility's name. zri is built from zri's dump and zri's production settings file, into a database named zf_zri, on zri's own port, and is served at http://zri.test. Which facility to copy depends on what you are working on. A facility with one principal investigator, where the PI is hidden on screen, behaves differently from one with several, where the PI is shown and chosen, so it is worth having one of each kind.

The database keeps the production name on purpose. How many principal-investigator seats a facility has was never written in any settings file; it is looked up by database name when a facility's settings are seeded, so a dev database with the production name inherits the real facility's contract with nothing to configure.

One dev facility is not a production facility's name: gui_test, which the automated browser tests run against. It is built from umaine's dump and settings into a database of its own, zf_gui_test, served at http://gui-test.test on port 3100, so a test run can create and delete whatever it likes without disturbing a facility somebody is reading. It alone gets three accounts with known passwords, one per role, which the tests sign in as.

Pick the facilities you want and use each one's name as <facility> below. The facility it is copied from is <source>: the same name, except for gui_test, whose source is umaine.

Get the source facility's settings and records

The copy is taken by a script that reaches the production host as do1, dumps the facility with the host's own mysqldump inside a single transaction, so nothing there is locked, and streams the result home. It also refreshes a local copy of that facility's production settings file first, so a credential rotated on the host can never strand you. Both land in gitignored directories, because both hold real researchers' names, addresses and a facility's database password, and neither ever travels by git.

The script refreshes only the settings files already present locally, so the first time, seed the one you need:

cd "$ZFM_ROOT_DIR"
mkdir -p db/env
scp do1:/var/www/zfm7/zebrafish-facility-manager/zf-server/environments/<source>.env db/env/

Then take the dump:

cd "$ZFM_ROOT_DIR"
scripts/dump-prod-facilities.sh <source>
ls db/dumps/<source>-prod-*

It keeps one known-good dump per source facility, and deletes the older one only when the new one reaches at least as high a stock number, since a stock number only ever moves forward. A dump that fails that check is kept beside the old one and the run says so and exits nonzero. Read the lines per facility rather than the exit status alone.

Build it

cd "$ZFM_ROOT_DIR"
scripts/rebuild-dev-facility.sh <facility>

One command, naming each thing as it does it:

  • Drops and recreates the database, and creates the facility's own database account if it is not there. Destructive to that dev database by design, and only ever to that one: the settings carry local credentials, so it cannot reach anything but the container.
  • Loads the dump. The dump's shape is the schema the migration chain starts from, so the chain's first step is recorded as already applied, and the rest of the chain runs.
  • Seeds the facility's settings record in its database from the production settings file you fetched, and writes the slim file the server runs on, zf-server/environments/<facility>.env. The production file is read as it is. What must differ on a dev machine is overridden on the way in: the database is the container, with the facility's own name as database, user and password; the address is http://<facility>.test; and the mail settings are not carried, so the shared settings' mail catcher applies. Everything else, the port included, is how the real facility is configured, and that is what the rebuild exercises.
  • Promotes the platform owner's account to super. Every dump carries that account at a lower role, and the screens a developer needs are gated on super. A real cutover does this as a deliberate step of its own; here it is done every time.
  • For gui_test only, adds three test accounts with known passwords, one per role, which the browser tests sign in as. The other dev facilities hold accounts that belong to people, and must not grow one of these.

Several names build several, one after another. scripts/rebuild-dev-facility.sh <facility> --dump <file.sql> builds one from a dump you name rather than the newest.

Am I ready to move on?

cd "$ZFM_ROOT_DIR/zf-server" && npm run check-config-syntax -- --facility <facility>
docker exec zfm-mysql mysql -uroot -prootpass -e 'SHOW DATABASES'

The first reads the facility's settings merged with the shared ones, the way its server will, and says a server would start on them. The second lists the facility's database among the container's.