Montagu

Prerequisites

• Docker Community Edition
• Docker Compose - at least version 0.17.0
• Python 3 and pip (Python 3 is included with Ubunti. For pip, use apt install python3-pip)
• Vault available on the command line as vault, with the address set via export VAULT_ADDR=https://support.montagu.dide.ic.ac.uk:8200
• Your machine needs to trust our Docker Registry. See "Configuring docker clients to use the registry"

Other docs process

• Release process
• Upgrading and rebooting servers, disaster recovery: docs
• Troubleshooting - potential issues and their solutions, particularly for getting Montagu running on a local dev environment.

Deploy

1. Install python packages with pip3 install --user -r src/requirements.txt
2. If restoring from backup (or making backups) prepare bb8 with sudo ./montagu-bb8/bb8/bb8_link_write
3. ./src/deploy.py

Deploy a specific version

./deploy.py v0.1.2

If the version number is omitted the script will prompt you for one (it must match the pattern of vX.Y.Z-RCa where X, Y, Z and a are one or more digits.

Use dockerhub containers

We also have all our released images on docker hub and the deploy tool can work from there. This requires VPN access only for the vault, so for test deployments can be done off-site more easily.

./deploy.py --docker-hub <version>

Settings

The deploy tool will ask you a series of questions interactively, suggesting defaults along the way. These settings are saved to ./src/montagu-deploy.json and on the next deploy those questions will not be asked. If new settings are added to the deploy tool, you will just be asked the new questions on your next deploy.

If you change your mind, you can directly change the values in the json file, delete the setting in question from the json file (prompting the tool to ask you just that question again next time you deploy) or delete the whole json file and go through the full interactive setup again.

Test users

If you use the 'test_data' data set then it comes with a default username ("test.user@imperial.ac.uk") and password ("password")

When deploying to a testing environment using real data restored from live, setting the add_test_user option to true adds the above user with permissions to all modelling groups and reports.

It will also add a "test.modeller@imperial.ac.uk" user who has access only to IC-Garske and Harvard-Sweet modelling groups.

Static files

To copy file artefacts from the orderly volume into the static volume where they can be served by the montagu-static file server, add a config file to the ./static directory in this repository. File artefacts will be copied into place following the directory structure of the config file, i.e. artefacts listed in a config file placed in ./static/model-review/2019 will be served from /www/model-review/2019. The config file itself must be a csv where each row contains 2 entries, the first being a glob identifying file artefacts within the orderly archive, the second being the directory to serve matching artefacts from.

So if a file at ./static/model-review/2019/config.csv contains row native-diagnostics-burden-report-drafts/20190131-123847-53fe189e/*,IC-Hallett the result is that all files matching the native-diagnostics-burden-report-drafts/20190131-123847-53fe189e/* glob will be served at model-review/2019/IC-Hallett

The montagu user

When deploying to the production server, make sure to first become the montagu user by connecting to production as montagu@production.montagu.dide.ic.ac.uk

Passwords

Database passwords are managed by the vault and laid out as:

/secret/vimc/database/:password_group/users/:username

Currently our two password groups are science and production

Retrieve

To get a database password for use with postgres

export PGPASSWORD=$(vault read -field=password secret/vimc/database/science/users/readonly)
psql -h support.montagu.dide.ic.ac.uk -U readonly -d montagu

This gets the password for the readonly user for the science password group (which is suitable for the database running on support.montagu.dide.ic.ac.uk). To see all users, use:

vault list secret/vimc/science/users

or

vault list secret/vimc/database/production/users

Add a new user

Run

./src/generate_passwords.py add_user <username>

Passwords can be regenerated by running the script

generate_passwords.py regenerate_passwords <group>

which will regenerate passwords for one of the password groups. To create a new password group, use

./src/generate_passwords.py create_password_group [--base=BASE] <name>

which generates a new set of passwords for the same users as the group specified by --base (defaulting to science).

Development

To update src/versions.py to the latest master of each sub repo, use src/update_versions_to_latest_master.py.

Fake SMTP Server

If the deployment setting fake_smtp is true, a fake SMTP server will be deployed. It provides a web interface at http://localhost:1080 showing the email requests it has received. It is used by the task queue component to send notification emails. If fake_smtp is false the component will be configured to use the Production SMTP server.

Configuration

Configuration of diagnostic reports to run when burden estimates are completed is defined in ./container_config/real_diagnostic_reports.yml This involves a lot of repetition as we currently run the same diagnostic report for each model, so this file can be regenerated by running ./src/generate_real_diagnostic_reports_config.py - any changes to the required configuration should be made through this script.

Logging

We log to systemd. All logs will have the tag DOCKER_TAG=montagu which allows for filtering with

journalctl --since=today CONTAINER_TAG=montagu
journalctl --since=today CONTAINER_NAME=montagu_db_1

Release

See ReleaseProcess.md for details on releasing