Developer documentation

https://unicef-invent.readthedocs.io

Run the Invent application locally

Table of Contents

1. Prerequisites
2. Start the Environment
3. Setting up the Environment
4. Troubleshooting

Prerequisites

Before you proceed, ensure that you have the following software installed on your machine:

1. Docker Desktop - (With Kubernetes enabled)
2. kubectl
3. Helm
4. Tilt
5. Python
6. Git

Start the Environment

Clone the repository using the following command:

git clone https://github.com/unicef/invent.git -b dev

Navigate to the project folder:

cd invent

Start the environment:

kubectl config use-context docker-desktop
tilt up

By navigating to http://localhost:10350/r/(all)/overview you can see the status of the resources. The "copy-dump" and "import-dump" Tilt resources are ok to crash if you don't have a sql dump named "dump_anon.sql" present in the root of the repository.

Setting up the Environment

Once all the services in Tilt (Postgres, Redis, Mailhog, Backend, Frontend) are up and running, initiate the DB:

kubectl exec deployments/invent-django -- python manage.py migrate

Create a superuser by providing the necessary information:

kubectl exec -it deployments/invent-django -- python manage.py createsuperuser

Next, go to the URL http://localhost/admin and login using the user you just created.

To create a User that can login to the Invent application, got to the Users section, under the "AUTHENTICATION AND AUTHORIZATION". Click on "ADD USER +" and fill out the fields as follows:

Field	Value
Username	As you wish (you’ll use the email address to log in)
Password	As per hint
Account type	Investor viewer (most accounts are of this type)
Name	A name that will be displayed in the INVENT page
Organisation	UNICEF (choose the one in all CAPS)
Country	As wished
Donor	UNICEF
Language	English
Global portfolio owner	Leave unchecked for a “normal” user
Country manager of	Leave unchanged for a “normal” user

Once ready, click "Save" (on the bottom right of the screen) and the page will reload with some additional fields.

Add the email address (which will be used to log in and for notifications). Leave all the other fields alone for a “normal” user.

To login with the "normal" user you just created, go to http://localhost/en/-/login and use the e-mail and password of the user.

Project structure

Static files (png, css, etc.) should go to:

nginx/site/static/

And can be accessed like:

http://localhost/static/css/some.css

http://localhost -- deployed frontend http://localhost/admin -- backend admin

Country map handling

1. Download the maps with the link in the admin page of the selected country
2. Unzip the map and load it in MAPSHAPER
3. Simplify the map as much as possible without loosing quality
4. Export the map from mapshaper as a geojson
5. Load the exported map file in the admin console and save the form
6. After the map is loaded use the admin interface to select the admin levels and hit save ( in the map tool )
7. Add a value in Map activated on ( be use the Today and Now buttons)
8. Save the form.

Production settings

On production, install a cron for the user (crontab -e) to autobackup the DB

0 4 * * * cd /path/to/project/django && fab backup_prod

Rebuilding search

You can rebuild search any time you want or if you realise there's some data missing from search

manage.py rebuild_search

Donor tools

When you delete a Donor from Django admin (as a superuser) and want to sync the donors in all projects:

manage.py remove_stale_donors

When you want to eg. remove a duplicate donor or a typo, you can migrate the project that use the typo or duplicate donor to the one that you want to keep for all projects:

manage.py switch_donor_form_to <DONOR_ID_YOU_WANT_TO_MIGRATE_FROM> <TO_DONOR_ID>

After migrating all projects, you can delete the typo / duplicate donor objects from the admin (don't forget to issue the remove_stale_donors after that.)

Translations command:

On Osx prerequisite is:

brew install gettext

after this command completes:

brew link --overwrite --force gettext may be needed

To scrape the code and extract translations: yarn translation:extract

To Update the translations files in the backend:

cd django
fab update_translations

To see the new string and modify translations: http://localhost/translation

(click on Save and Translate next block to save them)

To have translation appear in the frontend (after saving them at the previous step): docker-compose restart django

Quirks:

Translations are picked up from <translate></translate> blocks this block is declared as a global vue component so it can be used without importing it. If a translation string needs parameters (ie: {{userProfile.name}} hello!) the syntax is <translate :parameters="{name: userProfile.name}"> {name} hello </translate> Also, $gettext('english/base string') method is available in every Vue component via a mixin in the i18n plugin.