FlowKit-UI backend

A Flowkit query postprocessing, data management and authentication/authorisation component, designed for use with Flowminder/flowkit-ui.

The tool itself is containerised, so as long as you have Docker installed, it will take care of its own dependencies inside its container(s).

To build/run:

• Docker
• Make

To commit:

• pre-commit (for commit hooks)

Run the app via make. The following command will give you an overview of available targets:

make

You can use the following targets:

• deps: Regenerate pinned requirements.txt files
• build: build a new docker image (i.e. use the latest API spec)
• test: run all unit tests and produce a coverage report
• run: start the image, using the implementation directory as a bind mount (i.e. changes will be reflected by the flask server on the next API call)

Access the API at http://localhost:5000. The API document can be viewed at http://localhost:5000/openapi.json.

If you need to add any dependencies, add them to src/impl/requirements.in or src/impl/dev-requirements.in and refer to the section above as the docker image will have to be rebuilt.

Migrations between database versions are handled by https://alembic.sqlalchemy.org/en/latest/. By default, flowkit-ui migrations are targeted at the database running on localhost using the test credentials. To target migrations against remote dbs, create a file dev_credentials, staging_credentials and prod_credentials next to local_credentials, with the same structure. Then, pass Alembic the -x db_env={dev, staging, prod} option.

For example, the following brings the dev db to the latest Alembic migration

source .venv/bin/activate
python -m alembic -x db_env=dev upgrade head

Indicator labels, descriptions and method text (English and French) are defined in resources/config.json, but the running backend serves them from the indicator table in each environment's database. Nothing syncs the two automatically: no deploy or startup step reads config.json. To change indicator text, edit config.json, then generate and apply the SQL for each environment:

python3 resources/generate_translation_sql.py > /tmp/update_indicator_text.sql
tailscale ssh root@mobdash-sql-<env> "mysql --default-character-set=utf8mb4 -u root -A flowkit_ui_backend" < /tmp/update_indicator_text.sql

The script writes the English columns and the translation JSON in one transaction. Back up the table first (mysqldump flowkit_ui_backend indicator), and don't edit indicator text directly in the database, or config.json stops matching what's live. See the Haiti Mobility Dashboard wiki page for more.

• API_VERSION
• API_VERSION_URL_APPENDIX
• GIT_BRANCH
• GIT_COMMIT
• GIT_TAG
• APP_NAME
• IMAGE_NAME

 $ docker compose --env-file development_env up db
 $ python -m uvicorn --env-file development_env flowkit_ui_backend.main:app --host 0.0.0.0 --port 5000 --reload
 $ mysql -uhamster -hlocalhost -Dflowkit_ui_backend -P3306 --protocol=tcp -pTEST_PASSWORD 
 $ mysql -uhamster -hlocalhost -Dflowkit_ui_backend -P3306 --protocol=tcp -pTEST_PASSWORD < flowkit_ui_backend/db/mysql_schema.sql 
 $ mysql -uhamster -hlocalhost -Dflowkit_ui_backend -P3306 --protocol=tcp -pTEST_PASSWORD < tests/test_data.sql 

• DB_NAME
• DB_PORT_CONTAINER
• DB_PW
• DB_USER
• FLOWKIT_UI_URL
• CONTAINER_NAME_DB
• SERVER_PORT_HOST
• AUTH0_DOMAIN
• AUTH0_CLIENT_ID
• AUTH0_CLIENT_SECRET
• AUTH0_AUDIENCE

• DEV_MODE (default 0, set to 1 to enable)
• LOG_LEVEL (default to warning, default to debug if DEV_MODE=1)
• JUPYTER_ENABLED (default 0, set to 1 if using jupyter locally)
• JUPYTER_PORT