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:
The web app consists of a React front-end, and a Python Flask back-end.
Please check out Contribution Guidelines before you get started!
docker-compose
: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. Therefore copy example.env
into .env
To build and start the involved Docker services, execute
docker compose up
Open your web browser on http://localhost:3000
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
We are using Docker containers to make it easy for everyone to spin up an development environment which is the same everywhere. In docker-compose.yml
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
.
Boxtribute is an application for organisations who run distribution/warehouses in multiple bases. Therefore the development database seed holds at least two organisations and three bases:
BoxAid
working on Lesvos
andBoxCare
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)Coordinator
Volunteer
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.
Box in base 1
Box in base 2
Box in base 3
Box in base 4
More boxes can be found here.
More boxes can be found here.
We are 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
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.About the versioning scheme:
git commit -S -m "..."
to make your commits verifiable. See this ticket for more infogit checkout production && git pull --tags origin production
git pull origin master
git push origin production
git tag -s v2.X.Y
and push the tag with git push --tags
All our architecture decisions are logged in ADRs which you can find here. Here, is a list of intro tutorials for each technologies / frameworks / languages below.
See the LICENSE file for license rights and limitations (Apache 2.0).
This project was funded 3x by the German Federal Ministry of Education and Research (BMBF) via the Prototype Fund. Read more here (German only):