🦨

this is not an official kobotoolbox repository, okay?

kobo (some) docker

fighting complexity with simplicity by making humans do more work

goal

As a developer, I would like to run things I don't change inside Docker (PostgreSQL, Redis, MongoDB, and—for now—Enketo Express). I would like full, manual control over running code that I do change (kpi Python and kpi JS). I would like simplicity in configuration with sensible defaults and a minimum of mandatory customization.

to do

currently empty?!? 😮

getting started

1. clone https://github.com/kobotoolbox/kpi if you haven't already
2. docker-compose up, which should yield:
   • nginx listening at 10.6.6.1 on port 9000
     • this will reverse-proxy to kpi because the application does not run properly without nginx
   • enketo running on 10.6.6.1:9001
   • postgres, on 10.6.6.1:60666
   • redis, on 10.6.6.1:60667
   • mongo, on 10.6.6.1:60668
3. install os-level dependencies (sorry): sudo apt install python3.12-venv gcc python3-dev gdal-bin libpq-dev
   • more about GDAL here (it's required during migrations. and it's only required then?)
   • you'll also need docker and the compose plugin; tested with docker 27.2.1 and compose 2.29.2
4. python3 -m venv kpienv
   • tested with Python 3.12.3 on Ubuntu 24.04
5. set up a python development environment for kpi!
   1. . kpienv/bin/activate
   2. . envfile
   3. pip install pip-tools
   4. cd into your kpi source directory
   5. pip-sync dependencies/pip/dev_requirements.txt
   6. scripts/migrate.sh
   7. ./manage.py runserver 10.6.6.1:9010
      • ⚠️ not just any ol' runserver, okay?
6. set up a javascript development environment for kpi!
   1. open a new terminal
   2. cd into your kpi source directory
   3. nvm use 20.17.0, or whatever you cool kids like
   4. npm install
   5. npm run watch
      • are you lucky today? i am! webpack 5.92.1 compiled successfully in 16285 ms

🥧 "don't forget to manage your pie"

hints

1. django is set to use the console email backend, so you can do things like create user accounts and read the activation email details right from the output of ./manage.py runserver 10.6.6.1:9010
2. it might also be helpful to have a superuser account:
   1. go to the terminal where kpi ./manage.py runserver 10.6.6.1:9010 is running
   2. press ctrl+z to suspend runserver
   3. ./manage.py createsuperuser
   4. once you're done, type fg and press enter to bring runserver back to the foreground
3. help! i want to switch branches!
   1. you're generally responsible for knowing how to use ./manage.py migrate and its wrapper scripts/migrate.sh to apply database migrations (or revert them, by migrating backwards)
      • fyi, when going backwards, django lingo for the migration before 0001 is zero
   2. let's say you'd like to back up your databases and start from scratch to avoid migration hassles:
      1. stop ⚠️ the database servers with docker-compose stop
      2. rename the storage directory to something else
      3. restart the database servers with docker-compose up
      4. check out the new branch you'd like to use
      5. re-run scripts/migrate.sh
      6. you'll also have to recreate user accounts

nasties

• periodic tasks (celery beat) are completely ignored for the sake of simplicity
• apt install gdal-bin on the host unavoidable?
• "pyuwsgi is the exact same code as uwsgi but" actually has binary wheels?
  • it'd sure be nice not to compile uwsgi from source
    • then we could remove gcc and python3-dev requirements
  • unbit/uwsgi#1218 (comment)
• psycopg2-binary "is a practical choice for development and testing but in production it is advised to use the package built from sources."
  • the "why" is described here
  • for now, this means libpq-dev must be installed to avoid messing with Python requirements