Frontend Test Coverage:
Backend Test Coverage:
Build:
boxtribute
This is the repository for version 2 of the humanitarian relief web app Boxtribute. We support the distribution of over 1 million items each year and are deployed in over 15 locations across Europe and the Middle East (check our website for the most current list of partners).
Built by aid workers for aid workers, it is designed with three top priorities in mind:
- Quick deployment into crisis situations, including easy integration into a large range of relief operations, whether they're being newly set up or already up and running.
- Effective even with minimal training - doesn't require any professional expertise to use well. Can be run smoothly with short-term volunteers of all backgrounds.
- Dignity and choice-based distribution as a first priority for vulnerable individuals.
The web app consists of a React front-end, and a Python Flask back-end.
Please check out Contribution Guidelines before you get started!
Table of Contents
- Contribution Guidelines
- Installation
- Basic steps
- Front-end
- Back-end
- About Docker
- Development Database Seed
- CircleCI
- Architecture overview
- Sponsors
Preparation for Installation
- Clone the repository.
- Install Docker and
docker-compose (version 2)
How do I get set up?
:star2: Only TWO commands required to get the full-stack app up and running :star2:
At the end of this section, there are links to further instructions to set up additional tools for your front-end and back-end environment.
-
Environment variables are managed in a single file. Run cp example.env .env
-
To build and start the involved Docker services, execute
docker compose up
-
Open your web browser on http://localhost:3000
-
Log in with one of the test users listed below
NB: In case you get out-of-memory related errors, make sure your max memory is at least 4GB in your Docker settings (via Docker Settings UI -> Resources -> Memory) and try again.
In (Linux) Docker there is no UI to set the memory limits globally. In that case, please specify the following in docker-compose.yml:
version: "2.4"
services:
[...]
front:
mem_limit: 4G
Further Steps
About Docker
We use Docker containers to make it easy for everyone to spin up an development environment which is the same everywhere. In the docker-compose configuration file three Docker containers are specified - one for the MySQL database called db, one for the Flask back-end called webapp and one for the react front-end called front.
Development Database Seed
Boxtribute is an application for organisations who run distribution/warehouses in multiple bases.
Therefore the development database seed holds at least two organisations and four bases:
- Organisation
BoxAid working on Lesvos and
- Organisation
BoxCare working on Samos and in Thessaloniki and Athens.
Each organisation has at least 3 user groups with different access levels in the app:
Head of Operations (Admin access)CoordinatorVolunteer
In the development seed and Auth0 dev tenant we created the following login credentials with names telling their role and access to the various bases:
BoxAid (all have access to only one base: Lesvos):
BoxCare (there are 3 bases associated - Thessaloniki, Samos, Athens):
The password of all of these users is Browser_tests.
A collection of various QR labels (associated/not associated with existing boxes) can be found in this directory.
QR labels associated with boxes
Box in base 1
Box in base 2
Box in base 3
Box in base 4
QR labels not associated with any boxes
More labels can be found here.
QR labels that don't exist in the database
More labels can be found here.
CircleCI
We use CircleCI for automated testing of PRs and deployment to Google Cloud. To develop the CircleCI scripts you can run a CircleCI client locally. Please check out the documentation.
The most important commands are
circleci config validate
circleci local execute --job JOB_NAME
CircleCI development tips/learnings
- You can only trigger a job locally if it is part of a CircleCI workflow.
- Each
run-step in the config of CircleCI should be treated as its own terminal. If you have for example activated an virtual environment in a run-step, this environment is not activated in the next run-step.
Deployment
About the versioning scheme:
- major version is always 2
- minor version is incremented if any database migration is part of the release
- "bugfix" version is incremented otherwise
- Please commit (at least the last commit) using the command
git commit -S -m "..." to make your commits verifiable. See this ticket for more info
- Create a new list in trello named "Boxtribute 2.0 || merged to production date (v2.X.Y)"
- Move the cards from the list "Boxtribute 2.0 || merged to staging" to the new list
- Checkout the production branch and update it to the latest version:
git checkout production && git pull --tags origin production
- Merge master into production WITHOUT creating a merge commit (we want production to have the same history as master):
git pull origin master
- Publish the changes to the remote repo:
git push origin production
- Create a verifiable tag with the version number (check out the production branch after the merge, run
git tag -s v2.X.Y and push the tag with git push --tags
Architecture overview
All our architecture decisions are logged in ADRs which you can find here.
System landscape
The following diagram gives the system context for the boxtribute software acc. to the C4 model architecture visualization method.
Software stack
Here is a list of intro tutorials for each technologies / frameworks / languages.
Front-end
Interface
Back-end
Authentication
Testing
License
See the LICENSE file for license rights and limitations (Apache 2.0).
Sponsors
This project was funded 3x by the German Federal Ministry of Education and Research (BMBF) via the Prototype Fund. Read more here (German only):
