Skip to content

Developer Guide

Contributing to frb-master

If you are thinking of making code changes and feature development (or even a simple bug fix), please first open a Github Issue, then click on Development in the issue page to create a new branch that you can work on.

Pre-requisites

  • Python 3.9
  • Make sure you have the following packages installed in your machine:
  • curl
  • rsync
  • libldap2-dev
  • libsasl2-dev
  • git
  • gcc
  • make
  • openssh-client

You can install the above packages using apt or apt-get:

Text Only
sudo apt-get install curl rsync libldap2-dev libsasl2-dev git gcc make openssh-client

How to install the project

To clone the frb-master repo in your local environment, run the following command in your local terminal and inside a folder of your choice:

Text Only
git clone https://github.com/CHIMEFRB/frb-master.git
cd frb-master/

If you have a branch you would like to work on, run the following command:

Text Only
git checkout <issue-branch-name>

frb-master uses poetry for package management. To install the dependencies, run

Text Only
poetry shell
poetry install

Please make sure you have installed commitizen, or, if you prefer GUI over command line, have installed any Conventional Commit extensions in VSCode so that all the commits follow the conventional commit standard.

And now you are all set up to make code changes!

After you have completed your changes (and added tests and documentations!), please open a Pull Request on GitHub for your changes to be reviewed before deploying onsite.

Environment Variables

Below is a list of environment variables used for deploying the frb-master service with Docker.

  • FRB_MASTER_HOST -- Hostname the application will bind to, defaults to localhost
  • FRB_MASTER_PORT -- Port number the application will bind to, defaults to 8001
  • FRB_MASTER_WORKERS -- Number of processes to spawn, defaults to 2
  • MDB_HOST -- MongoDB hostname the application will attempt to connect, cluster default is frb-vsop.chime while compose default is mongo
  • MDB_PORT -- MongoDB client driver port, defaults to 27017
  • MDB_USERNAME -- MongoDB username, saved as a docker secret
  • MDB_PASSWORD -- MongoDB password, saved as a docker secret
  • DOCKER_BASE_URL -- Connection where to access the docker client, cluster default is tcp://frb-vsop.chime:4243, whereas compose default is unix://var/run/docker.sock
  • DOCKER_TIMEOUT -- Timeout for executing a command on the docker engine, default is 20.
  • DEBUG -- Debugging mode for frb-master, default is False, can be changed to true, 0, 1, yes, y Debug mode increases printing and also does a active reload of the app when any of the source files are edited.

Running tests locally

To run tests locally, run the following steps: (make sure you are in the frb-master/ folder)

Text Only
docker-compose up
A stream of logs will appear as different Docker containers start up. Once you see that frb-master is running: frb-master container running

In another terminal (make sure you are in the frb-master/ folder), run

Text Only
docker exec frb_master pytest
will execute all the tests under the tests/ folder. To run a specific test file, add /path/to/test after docker exec frb_master pytest.

test_swarm.py failing

When docker compose up is executed locally, it does not start a Docker Swarm; therefore, tests/test_swarm.py is expected to fail.

To stop, run:

Text Only
docker-compose stop

Deployment Guide

To deploy any changes onsite, first make sure that the latest releases are merged (look for any open Pull Request by github-actions like this) so that a new Docker image will be generated automatically by the Conitunuous Deployment GitHub Action.

Update Docker stack on frb-vsop

Now that a new Docker image has been generated, run the following command on frb-vsop.chime node ( ssh as frbadmin)

Text Only
cd frb-devops/stacks/core
git pull
docker stack deploy -c frb-master.yml frb_master --with-registry-auth
The Docker stack frb_master will be updated to run with the latest frb-master Docker image.

Roll Back Deployment

To roll back the version deployed onsite to the previous stable version, first identify the running version by going to https://frb.chimenet.ca/frb-master/version. To identify the last stable version, go to https://github.com/CHIMEFRB/frb-master/releases and locate the version tag before the latest release.

Version tags convention

frb-master uses conventional commit in order for release tags and CHANGELOG.md to be automatically generated/updated. That means, the version before v1.2.0 might be v1.1.1234 or v1.1.0; please double check the version number before rolling back.

With the newly deployed version identified, ssh into frb-vsop.chime as frbadmin, and run

Text Only
cd frb-devops/stacks/core
git pull
Then use nano or vim to change this line (L5) in frb-master.yml:
Text Only
    image: chimefrb/frb-master:latest
from latest to the last stable version (with 'v' included). After the change is saved, run
Text Only
docker stack deploy -c frb-master.yml frb_master --with-registry-auth

Remember to REVERT the Roll Back

The above changes to the frb-master.yml file is uncommitted and diverge from the main branch in frb-devops repo. In principle, any uncommitted change is prohibited from being deployed. After another stable version of frb-master is ready (with bug fixes) and a new Docker image generated, please revert the uncommitted changes by ssh-ing into frb-vsop.chime as frbadmin and run the following command:

Text Only
cd frb-devops/stacks/core/
git restore frb-master.yml
git pull
docker stack deploy -c frb-master.yml frb_master --with-registry-auth