Make it easier to Get Started and Troubleshoot

[anthonyfok]

Getting the opendrr-api stack build to run could be daunting especially for newcomers, but also for veterans setting it up in a new environment. So, here is a wishlist on ways to make it easier to get started and troubleshoot:

• Take the current documentation in README.md, expand the content and store in multiple Wiki pages e.g. "Getting Started" and "Troubleshooting", and have README.md link to the expanded documentation.

  • Update system requirements (disk space, expected run time, etc.)
  • Tell the user not to attempt the stack build unless he/she has obtained access to https://github.com/OpenDRR/CanadaSHM6 which private as of today (2024-03-26)
  • Add instructions for Podman Desktop (and maybe Docker Desktop too)

• Add detailed comments in sample.env and python/sample_config.ini to help the user configure them properly. For example:

  • if a variable is set elsewhere / in multiple places and they need to match? E.g. in docker-compose.yml too? Or hidden in a related container image?
  • for GitHub personal access token, which scopes should be granted, or link to

• Write a "wizard" script to help with initial configuration and troubleshooting, for example:

  • Check that .env and python/config.ini are in place and has file mode 0600 (readable by the user only)
  • Check that GitHub personal access token is in place and working
  • Check that Ports like 5432 (PostgreSQL) and 9200 (Elasticsearch) aren't preoccupied, and optionally shows which process(es) are occupying them and how to resolve (e.g. sudo systemctl stop postgresql)
  • Check that https://github.com/OpenDRR/CanadaSHM6 is accessible
  • maybe even Run docker compose up --build or podman compose up --build for the user directly
  • maybe even run tmux/byobu/screen with multiple windows/panels showing the docker compose logs of different running containers? (haha, for those of us not running Docker Desktop / Podman Desktop)