How To’s#

StudyGovernor Deployment#

The StudyGovernor is a complex system that uses external services: the data stored in a Postgres database, callbacks are executed on worker nodes, and to communicate between workers and the main process Celery with RabbitMQ is used. This means to run a StudyGovernor and have all functionality all these services need to be configured correctly.

Components overview

Components used in deployment of StudyGovernor#

To make deployment easier we provide ways to run the StudyGovernor using containers. For docker-compose and kubernetes basic configurations are provided.

Deployment using docker-compose#

In the repository there is a directory .docker that contains a docker-compose file. Starting a StudyGovernor is as simple as:

$ cd .docker
$ docker-compose build
$ docker-compose up

By default the StudyGovernor will be reachable at localhost:8000 and the account admin, password admin, will be available. The configuration of the StudyGovernor can be done by setting environment variables in the docker-compose file. For the list of variables to are used see the section ‘StudyGovernor Configuration’ at the end of this page.

Deployment using kubernetes#

Setting up a StudyGovernor on you own computer in K8s is as simple as executing a helm install.

$ kubectl create namespace studygovernor
$ helm install registry.gitlab.com/radiology/infrastructure/study-governor:8.0.0

The StudyGovernor should now be running on localhost/studygovernor and is ready to be setup.

Note

The repository contains helm charts for deployment using kubernetes. They can be found in the charts subdirectory.

Configuration values for kubernetes#

The following config values that map to environment variables are defined in the values.yaml:

Environment variable

Config value in Helm Charts

Notes

STUDYGOV_PORT

studygovernor.port

STUDYGOV_INSTANCE_NAME

studygovernor.instanceName

STUDYGOV_PROJECT_NAME

studygovernor.projectName

STUDYGOV_EMAIL_PREFIX

studygovernor.emailPrefix

STUDYGOV_EMAIL_FROM

studygovernor.emailPrefix

STUDYGOV_EMAIL_TO

studygovernor.emailPrefix

STUDYGOV_CALLBACK_METHOD

studygovernor.callbacks.method

STUDYGOV_EXTERNAL_HOSTNAME

studygovernor.externalHostname

STUDYGOV_EXTERNAL_PROTO

studygovernor.externalProtocol

STUDYGOV_EXTERNAL_PORT

studygovernor.externalPort

Default: service.port

GUNICORN_WORKER_CLASS

studygovernor.gunicorn.workerClass

GUNICORN_WORKER_CONNECTIONS

studygovernor.gunicorn.workerConnections

GUNICORN_TIMEOUT

studygovernor.gunicorn.timeout

DB_SCHEMA

studygovernor.db.schema

DB_NAME

studygovernor.db.name

DB_USER

studygovernor.db.user

DB_HOST

studygovernor.db.host

DB_PORT

studygovernor.db.port

STUDYGOV_ADMIN_USERNAME

studygovernor.admin.username

STUDYGOV_ADMIN_EMAIL

studygovernor.admin.email

STUDYGOV_ADMIN_PASSWORD

studygovernor.admin.password

STUDYGOV_ADMIN_FORCE_UPDATE

studygovernor.admin.force_update

SCRIPT_NAME

$pathPrefix

Default value derived from Ingress

APPLICATION_ROOT

$pathPrefix

Default value derived from Ingress

PROJECT_REPO

studygovernor.project.git.url

Enabled by studygovernor.project.git.enabled

PROJECT_BRANCH

studygovernor.project.git.branch

PROJECT_RELATIVE_PATH

studygovernor.project.git.relativePath

STUDYGOV_XNAT_PROJECT

studygovernor.fastr.xnatProject

STUDYGOV_PROJECT_HOME

studygovernor.fastr.projectHome

STUDYGOV_PROJECT_SCRATCH

studygovernor.fastr.projectScratch

SECURITY_REGISTERABLE

studygovernor.security.registerable

SECURITY_CHANGEABLE

studygovernor.security.changeable

SECURITY_RECOVERABLE

studygovernor.security.recoverable

SECURITY_CONFIRMABLE

studygovernor.security.confirmable

Setting up a development environment for kubernetes#

You need a number of tools to start developing for the StudyGovernor on kubernetes locally.

Once you have docker, k3d, helm and Tilt installed a kubernetes cluster need to be created. There is a Makefile that will create a basic cluster using k3d:

$ make up

The a development environment can be started by using the Tiltfile in the repository root:

$ tilt up

The StudyGovernor will be available at localhost/studygovernor by default. The admin account will be set to admin, password supersecretpassword.

To stop running the system use the following commands:

$ tilt down
$ make down

The first command stops all StudyGovernor containers and the second command clean up the kubernetes cluster.

Setting up local development environment#

If you want to set up a local development environment for either developing or just testing the StudyGovernor, a MySQL/mariadb database and rabbitmq need to be provided.

The database needs to be initialized:

# Go the mysql command line (add the -p if you have set a root password).
$ sudo mysql (-p)

# Create user
mysql> CREATE USER '<username>'@'localhost' IDENTIFIED BY '<password>';

# Create database
mysql> CREATE DATABASE studygovernor;

# Grant all permissions of the database to the user.
mysql> GRANT ALL ON studygovernor.* TO '<username>'@'localhost'; ``

The <username> and <password> needs to be replaced with a username and password of your choice.

Then you can create a .env in the directory from which you want to run the StuydGovernor. A minimal example (matching the bove database creation) would be:

FLASK_APP="studygovernor"
SQLALCHEMY_DATABASE_URI = "mysql+pymysql://<username>:<password>@localhost/studygovernor"
SECURITY_PASSWORD_SALT="<password salt>"
SECRET_KEY="<secret key>"
STUDYGOV_XNAT_PROJECT="TEST"

The password salt and secret key are used for security purposes. The password salt is described in the FlaskSecurity documentation The secret key is described in the Flask documentation The StudyGovernor needs to be installed in your environment before you can run it, this can simply be done from pypi using pip or from sources in case you want to develop StudyGovernor. Installation from pypi using pip is as simples as:

pip install studygovernor

If you want to develop from source we assume that you know how to install a Python package yourself. Now everything is set up, starting the app can be done using Flask:

$ flask run

StudyGovernor Configuration#

The StudyGovernor is configured using environment variables. Alternatively a .env file can be provided to define config variables, for this we use python-dotenv There are a number of import variables that are required:

Variable

Req

Description

SQLALCHEMY_DATABASE_URI

YES

STUDYGOV_CELERY_BROKER

YES

SECURITY_PASSWORD_SALT

YES

SECRET_KEY

YES

STUDYGOV_XNAT_PROJECT

YES

STUDYGOV_PROJECT_HOME

NO

STUDYGOV_PROJECT_SCRATCH

NO

STUDYGOV_INSTANCE_NAME

NO

STUDYGOV_PROJECT_NAME

NO

STUDYGOV_PROJECT_BIN

NO

STUDYGOV_PROJECT_NETWORKS

NO

STUDYGOV_PROJECT_TASKS

NO

STUDYGOV_PROJECT_TEMPLATES

NO

STUDYGOV_PROJECT_WORKFLOWS

NO

STUDYGOV_EMAIL_FROM

NO

STUDYGOV_EMAIL_TO

NO

STUDYGOV_EMAIL_PREFIX

NO

SECURITY_REGISTERABLE

NO

SECURITY_CHANGEABLE

NO

SECURITY_RECOVERABLE

NO

SECURITY_CONFIRMABLE

NO