Akvo MIS

Real Time Monitoring Information Systems

Prerequisite

• Docker > v19
• Docker Compose > v2.1
• Docker Sync 0.7.1

Development

Environment Setup

Ensure that PORT 5432 and 3000 are not being used by other services.

Copy env.example to create a .env file. Here’s what it should look like:

.env

APP_NAME="Akvo MIS"
APP_SHORT_NAME="akvo-mis"
APK_NAME="MIS Mobile"
APK_SHORT_NAME="mis-mobile"
DB_HOST=db
DB_PASSWORD=password
DB_SCHEMA=mis
DB_USER=akvo
DEBUG="True"
DJANGO_SECRET=local-secret
GOOGLE_APPLICATION_CREDENTIALS
MAILJET_APIKEY
MAILJET_SECRET
WEBDOMAIN
EXPO_TOKEN="<<your secret expo token>>"
POSTGRES_PASSWORD=password
PGADMIN_DEFAULT_EMAIL=dev@akvo.org
PGADMIN_DEFAULT_PASSWORD=password
PGADMIN_LISTEN_PORT="5050"
IP_ADDRESS="http://<your_ip_address>:3000/api/v1/device"
APK_UPLOAD_SECRET="123456789AU"
STORAGE_PATH="./storage"
SENTRY_DSN="<<your sentry DSN for BACKEND>>"
SENTRY_MOBILE_ENV="<<your sentry env>>"
SENTRY_MOBILE_DSN="<<your_sentry_mobile_DSN>>"
SENTRY_MOBILE_AUTH_TOKEN="<<your_sentry_mobile_auth_token>>"

You can generate a Sentry auth token by following this official Sentry documentation.

Start

For initial run, you need to create a new docker volume.

./dc.sh up -d

docker volume create akvo-mis-docker-sync

Note: On some linux systems, you may need to change the permissions of the directory where the volume is stored.

The development site should be running at: localhost:3000. Any endpoints with prefix

• ^/api/* is redirected to localhost:8000/api
• ^/static-files/* is for worker service in localhost:8000

Network Config:

• setupProxy.js
• mainnetwork container setup

Add New User and Seed Master Data:

Once the containers are up and running, you can seed the necessary data by running the following command:

./dc.sh exec backend ./seeder.sh

The script will prompt you for various actions related to data seeding such as:

• seed administrative data
• add a new super admin
• seed fake users
• seed forms

Answer each prompt by entering 'y' or 'n' followed by the Enter key.

Default Fake User's password: Test#123

Generate QR Code for Mobile App Download:

To generate a QR code image for the mobile app download link, run:

./dc.sh exec backend python manage.py generate_qr_code

This generates a QR code PNG image at storage/images/download-app.png encoding the default URL (WEBDOMAIN/app).

To specify a custom URL:

./dc.sh exec backend python manage.py generate_qr_code --url https://example.com/app

Log

./dc.sh log --follow <container_name>

Available containers:

• backend
• frontend
• mainnetwork
• db
• pgadmin

Stop

./dc.sh stop

Teardown

./dc.sh down -t1
docker volume rm akvo-mis-docker-sync

Mobile App Development

For initial run, you need to create a separate docker volume.

docker volume create akvo-mis-mobile-docker-sync

./dc-mobile.sh up -d

1. Install the Expo Go app from Playstore
2. Connect your android to the same wireless network as your machine.
3. Open The Expo Go
4. Enter URL Manually: Your_IP_Address:19000

Teardown Mobile App

./dc-mobile.sh down -t1

Production

export CI_COMMIT='local'
./ci/build.sh

Above command will generate two docker images with prefix eu.gcr.io/akvo-lumen/akvo-mis for backend and frontend

docker-compose -f docker-compose.yml -f docker-compose.ci.yml up -d

Network config: nginx

Data Seeder

Akvo Flow

The Akvo Flow Data Seeder enables you to migrate data from Akvo Flow to Akvo MIS. The process involves downloading forms and data, mapping administration and question data, and seeding the final data via Docker.

Quick Start Steps:

1. Navigate to the scripts directory:

   cd scripts/akvo-flow

2. Configure environment: Copy env.example to .env and populate with your Akvo Flow credentials

3. Configure survey IDs: Update flow_ids in af_downloader.ipynb and af_forms_mapping.ipynb with your target surveys

4. Start JupyterLab:

   jupyterlab .

5. Download forms and data: Run all cells in af_downloader.ipynb

6. Map administration data: Run all cells in af_administration_mapping.ipynb

7. Map form questions: Run all cells in af_forms_mapping.ipynb

8. Generate parent and child data files: Run all cells in af_data_registration_monitoring.ipynb to produce the final data files in the output folder

9. Pre-download photos (optional but recommended): If your forms contain photo questions, pre-download them before seeding:

   python manage.py predownload_photos --form=<akvo_flow_survey_id>

   Optional parameters:

   • --workers=<number> - Number of concurrent download workers (default: 5)

   This creates a success log at storage/akvo-flow/<form_id>_photo_downloads.csv and a failed log at storage/akvo-flow/<form_id>_photo_downloads_failed.csv for manual review. Re-running skips already downloaded photos.

10. Seed the data: Run the Django management command:

    python manage.py flow_data_seeder --form=<akvo_flow_survey_id> --email=<youremail@domain.com>

Optional parameters:

• --limit=<number> - Limit the number of records to process
• --revert=True - Revert previously seeded data

For comprehensive documentation covering environment setup, detailed command explanations, output expectations, and troubleshooting, see the Akvo Flow Data Seeder Guide.