Skip to content

BecomingMaintainer

Jump to bottom
peder2911 edited this page Aug 10, 2021 · 9 revisions

Becoming a maintainer

Through a series of tasks, this article aims to bring you up to speed with how to run ViEWS 3, how to fix common issues, and how to contribute new functionality to the system. After completing these tasks, you will have the competence to run and admin ViEWS 3.

Task -1: Authentication

  • Azure SP credentials

Task 0: System requirements

Prerequisites:

  • docker => 19.03.8
  • docker-compose >= 1.28.6

Task 1: Running ViEWS 3

ViEWS 3 is a [system of services][Architecture]. Each service runs in a separate process, and communicates with other services over HTTP. Services are all Docker containers, and can easily be put up using Docker Compose.

  1. Clone the prio-data/views3 repository.

Authenticating

ViEWS 3 uses Azure for storing Docker images, settings and secrets, and caching. The Azure resources are not generally accessible, and require authentication to reach. You authenticate to Azure by providing an auth-file to the running containers, and by authenticating with the Docker cli. To be able to authenticate, you must be given a file with the proper credentials by an administrator.

  1. Log in to ACR with Docker

Since the ViEWS 3 images are contained in a private registry, you must authenticate with the ViEWS Docker repository before you can download the images and run the composition. Information on how to do that is located here.

  1. Point to the authentication file

To pass the information from the authentication file to the Docker containers spun up by Docker compose, create a file named .env in the directory containing the views 3 repo containing the following line:

AUTH_FILE={PATH_TO_AUTH_FILE}

replacing {PATH_TO_AUTH_FILE} with the path to the authentication file on your system. This passes the authentication information on to each container, allowing them to communicate with Azure.

Running

  1. Pull the images
docker-compose pull

This fetches the latest version of the images for each of the services.

  1. Put up the composition

Once you have these, you can run

docker-compose up

Congratulations! You now have ViEWS3 running locally on your computer.

Task 2: Altering a service

To develop on the services comprising ViEWS 3, you need to rebuild and replace services with changes. First of all, you need the code for all of the services. If you have already cloned the prio-data/views3 meta-repository, enter it and run:

git submodule init
git pull --recurse-submodules

This downloads the repository for each service. You make changes to a service by editing the code within one of the repositories. Once you have edited some code, and want to see how it works in concert with the other services, run:

docker-compose build

Then to start the composition, you run

docker-compose up

A very practical one-liner that rebuilds and restarts only the services that have changed is:

docker-compose build && docker-compose up --no-deps -d

This lets you quickly iterate on services, seeing how they work after a quick compile-step.

Clone this wiki locally