Getting started

Local setup¶

This assumes you will use the docker compose file in this repo to run services. If that is not the case you may need to edit some settings.

Python environment¶

Install uv to manage Python versions and dependencies:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a virtual environment in .venv and install the requirements:

uv sync

Activate it (or prefix commands with uv run):

source .venv/bin/activate

Install the git hooks and run them once:

prek install

prek run -a

Create your env file and edit the settings as needed (or export settings directly):

cp .env_template .env

GeoDjango / PostGIS¶

Connect uses GeoDjango and PostGIS. To learn more about the required dependencies, see the Django documentation.

For macOS (Intel / Apple Silicon) – using Homebrew:

brew install gdal geos proj

Django may struggle to find the GDAL and GEOS libraries even after they are installed. Get your local library paths:

ls $(brew --prefix gdal)/lib/libgdal.dylib

ls $(brew --prefix geos)/lib/libgeos_c.dylib

Then set them in your .env file:

GDAL_LIBRARY_PATH=...
GEOS_LIBRARY_PATH=...

Install WeasyPrint:

brew install weasyprint

For Ubuntu / Debian Linux:

sudo apt-get install -y binutils libproj-dev gdal-bin

Enabling the PostGIS extension

No migration creates the postgis extension. The inv up setup works because the postgis/postgis image enables it for you when it initialises the database.

If you are using your own PostgreSQL instead, create the extension in the target database before migrating, or the first spatial migration will fail:

psql -d commcare_connect -c "CREATE EXTENSION IF NOT EXISTS postgis;"

Running the app¶

Start the docker services (PostgreSQL/PostGIS and Redis):

inv up

Install the JS dependencies and build them (add -w to rebuild on changes):

npm ci

inv build-js

Migrate the database and start Django:

./manage.py migrate

./manage.py runserver