Skip to content

BecomingMaintainer

Jump to bottom
peder2911 edited this page Aug 11, 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.

You should refer to the articles on the architecture and technologies used whenever you come across a term or idea you are not yet familiar with. I strongly encourage you to follow the links in those articles, to get a good, solid understanding of concepts and technologies applied here.

These steps take you on a lightning tour of how to run ViEWS 3, and then go into detail about how to contribute new code.

Task 0: System requirements

Since ViEWS 3 runs in docker, it has a very light footprint in terms of system dependencies. All you need is to have docker, and docker-compose installed on your system with the following versions:

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

If you're on OSX, you should use Docker Desktop, which should give you the CLI features you need. If you're on linux, you're probably a genius who doesn't need my help.

With these two components installed, you are ready to run views 3 locally.

Task 1: Running ViEWS 3

ViEWS 3 is a system of services. 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:
git clone https://github.com/prio-data/views3 $HOME/views3

This oneliner clones the views3 repo into your home (user) directory. Of course, feel free to clone it to whatever folder you like. Note that views3 is a metarepository.

Authenticating with Azure

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.

Once you have the credentials file, you could source it, setting the values in your shell environment. This makes it possible to run the subsequent commands in this tutorial without changing anything:

source $HOME/my_auth_file

To see if this worked, try running this command and verify that it outputs a URL:

echo $ACR_HOSTNAME
  1. Log in to ACR with Docker

Since the ViEWS 3 images are contained in a private registry (ACR), you must authenticate with the ViEWS Docker repository before you can download the images and run the composition. More information about why and how to do that is located here.

After sourcing the auth file you've recieved (previous step), you can run the following command to log into the ACR:

docker login $ACR_HOSTNAME --username $AZURE_CLIENT_ID --password $AZURE_CLIENT_SECRET

To verify that you're logged in, try running this command:

docker pull $ACR_HOSTNAME/uvicorn-deployment

This should download the uvicorn-deployment image to your system. This image is the basis of many of the services used in ViEWS 3!

  1. Point services to the authentication file

As was also mentioned in the article about Azure, services need to be able to log into various Azure services as well. This is done by providing each service with credentials in their environment. 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 ($HOME/views3 if you've followed this tutorial verbatim) 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. The values in the env file are accessible by docker compose, and are used when spinning up the system, giving each service the proper credentials.

Running

If you have followed the previous steps, you have all the prerequisites for running views 3! Now, navigate to the views 3 repository folder (again, $HOME/views3 if you've followed the tutorial verbatim) before running the following commands.

  1. Pull the images

First, you must retrieve the images for each service. You do this by simply running:

docker-compose pull
  1. Put up the composition

Once you have the images, you can simply 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