rodekruis / ibf-system

Tools required to trigger, manage and execute the Red Cross Early Action Protocols for natural disasters.

IBF-system

Status

Component	Build Status
Cypress Integration Tests

Introduction

NOTE: Some background on IBF-terminology (e.g. triggers) is expected. This can be expanded on later.

This is the repository for the IBF-system. It includes a.o.:

1. An API-service (backend)

• which accepts input from various IBF-pipelines, that upload impact forecast data to the IBF-system on regular intervals. (See 'Dependencies' below.)
• and which lets the IBF-dashboard - or other authorized accounts - retrieve data from the IBF-database.

2. An IBF-dashboard (frontend)

• showing all impact forecast data - either leading to a trigger or not - in the IBF-portal

3. A features folder describing all feature scenarios in the IBF-system, using Gherking language.

4. A docs folder with further documentation beyond this readme.

Dependencies

• The IBF-dashboard will not show meaningful information (or even load correctly) without impact forecast data being uploaded to it.
• This data is provided by separate IBF-pipelines, that are not part of this repository, but are strongly connected.
• See the 510 IBF Project Document for more info and links to the 510-instances of these pipelines per disaster-type.
• For development/testing purposes, there are mock-endpoints and mock-data available to replace the need for these pipelines. (See 'Load local database with data' below.)

System design

Getting Started

Setup a local development-environment:

• Install Git: https://git-scm.com/download/

• Install Node.js: https://nodejs.org/en/download/

  • Install the version specified in the .node-version-file.

  • To prevent conflicts between projects or components using other versions of Node.js it is recommended to use a 'version manager'.

    • NVM - Node Version Manager (for macOS/Linux).

    • NVM for Windows (for Windows)

    • FNM (for Windows/macOS/Linux)

Installation

1. Clone the repository

2. Setup env variables:

   cp example.env .env

   Fill in the .env variables with someone who has them.

3. Run npm run install:interface

Start apps

From root run

• npm run start:services
• npm run start:interface

Load (local) database with data

When running Docker locally, a database-container will start (as opposed to remote servers, which are connected to a database-server). For setting up a fully working version of the IBF-dasbhoard 2 steps are needed.

1. Load initial raster data

• Get the file raster-files.zip from this folder.
• Unzip it in services/API-service/geoserver-volume/raster-files folder, such that that folder now has subfolders:
  • input-folder: static raster files that are served through 'geoserver' to the 'IBF-dashboard'
  • mock-output-foldermock output raster files that are used by the mock-endpoint (see below)
  • output-folder: currently empty, but any raster files that are posted to the API-service by IBF-pipelines (or mock endpoint) will be stored here, and Geoserver will be able to read them from here.

2. Post static data and 1st batch of dynamic data to database

• login http://localhost:4000/docs#/--%20user%20--/UserController_login (click Try it out, fill in your username and password, and click Execute)
  • Copy the resulting user.token of that api call
  • Paste it to the Authorize button button at the top of that page
• by calling mock-endpoint
  • see API documentation: http://localhost:4000/docs/#/scripts
  • run for all countries and disaster-type at once: http://localhost:4000/docs/#/scripts/ScriptsController_mockAll
  • or run for 1 country and 1 disaster-type: http://localhost:4000/docs/#/scripts/ScriptsController_mockDynamic
• or by having external pipeline make a call to IBF-system

Installation result

These commands will install the IBF-system with listeners at,

1. localhost:4000/docs for the API-service documentation
2. *development only - localhost:4200 for the web interface

Troubleshoot installation issues

Please read the troubleshoot guidlelines to support the insatllation of IBF in the TROUBLESHOOT.md

Integration tests

Cypress (THE USE OF CYPRESS IS DEPRECATED FOR IBF)

We use Cypress for automated integration testing in this project. Installation:

0. (Potentially on Ubuntu?: sudo apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb)

1. In root folder npm install --only=dev

   • This should download and install Cypress
   • If it fails, find out why and/or install Cypress in some other way (e.g. npm install cypress)

2. Set necessary environment variables by copying cypress.env.json.example to cypress.env.json and filling in the variables.

3. Run npm run cypress:open

   • When the Cypress window opens click on 'Run X integration specs'
   • Alternatively run npm run cypress:start to run from commandline

Releases

See notable changes and the currently released version in

• CHANGELOG, which is automatically created based on commit messages
• What's new in IBF, which is manually created at every release (see also release checklist below)

Release Checklist

• Check if the latest integration tests passed on Cypress Dashboard.
• Pick a tag to release. Generally this is the latest tag in tags.
• Click the 'Create release' button.
• Enter as release title the tag-name (e.g. v0.128.5).
• IMPORTANT: Before actually doing the release (and thus releasing to staging), check if any .ENV-variables on the server need to be updated. Do that by SSH'ing into the server and making the required changes. This will make sure the new release will use the updated .ENV-variables immediately.
• Click the 'Publish Release' button.
• IMPORTANT: Add changes relevant to the end-user in What's new in IBF

The above steps should trigger the release webhook which updates the staging environment to the published release. This takes a while (approx 20 mins) to update.

Deployment

To "test" environment

• Make sure to verify if the environment-settings are appropriately set on the test VM before merging the PR.
• Merging a PR to master will lead to creation of a new tag (e.g. v0.128.5), but ONLY if the PR includes at least 1 commit with a commit message starting with 'feat: ' or 'fix: ' (following Conventional Commit)
• The tag creation in turn will lead to an automatic deploy to the test-server (via webhook, see: /tools#GitHub-webhook)
• Wait until deploy is ready (by checking when the new version-number has appeared on the login-page of IBF-dashboard)
• Run seed-script
• Run 'mock-all' endpoint

To "stage" environment

• Make sure to verify if the environment-settings are appropriately set on the stage VM before publishing the release.
• When a release is published, it is automatically deployed to the staging-server.
• Wait until deploy is ready (by checking when the new version-number has appeared on the login-page of IBF-dashboard)
• Note that the deployment logs can be followed in /var/tmp/ibf-<yyyy-mm-dd>.stdout.log
• Run seed-script
• Run 'mock-all' endpoint

To "production" environment

• SSH into the production server
• Make sure to verify if the environment variables are appropriately set on the VM.
• Currently the deploy-script must be run in sudo-mode. See this section of the TROUBLESHOOT guide.
• Manually run the deploy script with the tag which should be deployed for the specific country.
• Sometimes npm packages are not all automatically correctly installed. In case of issues with the api-service restart after deployment has finished, check the this section of the TROUBLESHOOT guide

Contributing to IBF

Please read the contributing guidlelines in the CONTRIBUTING.md

Glossary

Term	Definition (we use)
version	A 'number' specified in the SemVer-format: 0.1.0
tag	A specific commit or point-in-time on the git-timeline; named after a version, i.e. v0.1.0
release	A fixed 'state of the code-base', published on GitHub
deployment	An action performed to get (released) code running on an environment
environment	A machine that can run code (with specified settings); i.e. a server or VM, or your local machine

ibf-system's Issues

Docker-compose does not activates all the containers

Description

Upon running the <docker-compose -f docker-compose.yml -f docker-compose.override.yml up> all the containers are not started mentioned in the docker-compose file. Some containers throw certain errors mentioned below

To Reproduce

◦	docker-compose up -d
◦	docker-compose stop ibf-dashboard
◦	cd interfaces/IBF-dashboard
◦	npm start

Expected behaviour
All containers mentioned in the docker-compose file /IBF-system/docker-compose.yml be up and running.
Application should load and respond properly on the localhost:4200.

Screenshots
Attached below.

Desktop (please complete the following information):

• OS: MAC OS
• Browser : chrome
• Version : 92.*

Workaround
The containers ibf-system_ibf-pipeline , ibf-system_ibf-api-service do not start

The container and do not start automatically via the docker compose up command. The workaround for this would be, manually start the container and and run this command.

• docker compose exec ibf-pipeline python3 runPipeline.py

These below commands come in handy when you face such issue:
1 docker-compose -f docker-compose.yml -f docker-compose.override.yml up
2 docker compose exec ibf-api-service bash
3 docker compose exec ibf-pipeline python3 runPipeline.py
4 docker-compose exec ibf-api-service npm run seed
5 docker-compose up -d ibf-api-service
6 docker-compose logs -f ibf-api-service
7 docker-compose restart ibf-api-service
8 docker-compose exec ibf-api-service npm install

Use them as and when needed

Dependabot couldn't find a package.json for this project

Dependabot couldn't find a package.json for this project.

Dependabot requires a package.json to evaluate your project's current JavaScript dependencies. It had expected to find one at the path: /interfaces/overview/package.json.

If this isn't a JavaScript project, or if it is a library, you may wish to disable updates for it from within Dependabot.

View the update logs.