Prerequisites

This page is what you arrange before you deploy ZFM. Most of it is information you will be asked for later during the rest of the deployment.

For production

The hosts

You need two hosts: one where you build the installation artifact, and one that runs the live system. One machine can do both, which is how a test deployment is usually done.

You need command-line access to both, usually ssh, with an account that can use sudo.

From the production host, collect its public IP address. Every facility's DNS record points at that address, and the database server's allow-list has to name it before the host can connect.

The domain and its DNS

Choose and register a domain name, or use one you already have. Each facility's web address will be a sub-domain of it, and the system will send emails from that domain. Choose the name carefully, because it will be very hard to change once customers are up and running.

Then its DNS. Each facility's web address is a sub-domain with an A record pointing at the production host's public IP address. A DNS change can take a few hours to publish, so make the records now rather than on the day you need them.

ZFM resolves that name itself. A facility whose address begins https:// is refused unless its name already reaches the host it is being created on, because a certificate authority will not issue a certificate for a name that answers somewhere else. So a record that was never made, or one still pointing at a host you have moved off, stops a facility before it is built rather than after.

The database server

Each facility's records live in a database of its own, and ZFM creates those databases itself, so it needs an account on the server that can. Every facility on a host can share one database server, and by default they do. Set that server up now and collect what the later pages ask for.

A managed MySQL 8.4 service. Create the instance in the provider's console. A managed service normally requires TLS rather than offering it, and refuses a connection from any machine it has not been told about, so name every machine that will talk to the database in the service's allow-list. What to collect:


`DB_HOST`, `DB_PORT`	the address the service assigns. Read the port off the console rather than assuming it: it is `3306` only by convention, and `25060` on DigitalOcean
`DB_SSL_CA`	the certificate authority the connection is verified against, downloaded from the service's own page
the database administrator's account	the privileged account the service issues, with its password

MySQL 8.4 you run yourself. Match the version of any managed service you might move to later, and configure TLS if anything will connect over a network. What to collect:


`DB_HOST`, `DB_PORT`	where the server answers. The port is `3306` only by convention
`DB_SSL_CA`	the certificate authority, if you gave the server a certificate of its own
the database administrator's account	`root`, and the password you set for it

You also need a way to run SQL as that account, from a machine the allow-list names: a mysql command-line client, or a database tool such as DataGrip.

Am I ready to move on?

mysql --host=<db-host> --port=<db-port> --user=<admin> --password \
  --ssl-ca=<the CA file you downloaded> -e 'SELECT VERSION()'

It answers with the server's version, which says the address and port are right, the certificate verifies, the administrator's password works, and the machine you are sitting at is in the allow-list. A database tool such as DataGrip tests the same things.

Outbound email

ZFM sends email to its users — an invitation when you create one, a password reset when somebody asks for one. So an outbound mail server is required.

Leave this until the domain resolves. A provider cannot verify a domain whose DNS is not live yet, and the records it asks you to add take the same few hours to publish as the ones you have already made.

dig +short NS <domain-name>

When that prints the nameservers of the service where you add records, the domain is delegated to it and a provider can read what you put there.

Every facility on a host can share one mail account, and by default they do. Set that account up now: you need a provider that will accept SMTP from your production host and send as an address at your domain. The provider will take you through verifying that you own the domain. Collect the following as you go:


`MAIL_FROM`	the address users see mail come from
`MAIL_HOST`, `MAIL_PORT`	the provider's SMTP endpoint
`MAIL_TLS_MODE`	how the connection is encrypted: `starttls` on port 587 or `implicit` on 465, whichever the provider documents. A third value, `none`, is for the mail catcher on a development machine and takes no credentials
`MAIL_USER`, `MAIL_PASSWORD`	the SMTP credential, which is usually not the same as your console login at the provider.

ZFM sends from an address in the domain your facilities sit under: with facilities at zri.example.org and udemo.example.org, mail comes from something like admin@example.org. That is the address the provider verifies and the one you write as MAIL_FROM. An address at a free provider such as gmail.com is not yours to verify, so it cannot be used.

Any SMTP service works, because ZFM asks nothing of a provider beyond those values.

Am I ready to move on?

Send yourself a message with the values you just collected. curl speaks SMTP, so this needs nothing installed:

printf 'From: foo@<domain-name>\nTo: <your own address>\nSubject: ZFM mail check\n\nIt works.\n' |
  curl --url 'smtp://<MAIL_HOST>:<MAIL_PORT>' --ssl-reqd \
    --user '<MAIL_USER>:<MAIL_PASSWORD>' \
    --mail-from 'foo@<domain-name>' --mail-rcpt '<your own address>' \
    --upload-file -

Silence means the provider accepted it; anything wrong is reported. Use smtps:// in place of smtp:// for a provider on port 465, where the connection is encrypted from the first byte rather than from the STARTTLS that --ssl-reqd asks for.

Send it from any address at your domain — foo@<domain-name> will do, since what the provider verified is the domain and not a mailbox. Arriving proves the four values are right and that the provider will send as your domain, which is everything ZFM needs of it.

For development

A development machine substitutes two of these, and needs no domain, no mail provider and no managed database:

The databases live in a container on that machine, so DB_HOST and DB_PORT point at it and there is no DB_SSL_CA to supply.
Mail goes to a catcher, not to a mail provider: an SMTP server that accepts everything, delivers nothing, and shows you what was sent in a web inbox. MAIL_TLS_MODE=none with no credentials. This is not just convenience — a dev facility built from a production dump holds real researchers' email addresses, and a password reset sent from a dev box with working mail settings would reach one of them.

Setting a development machine up is its own guide, which follows this one page for page: Development, starting at its own prerequisites.