Contributing/Local development/Backend setup

guidecontributingCARE 3.0+

This page walks you through running the Care backend ([https://github.com/ohcnetwork/care ohcnetwork/care]) on your machine. It is a Django application that exposes the Care REST API and depends on PostgreSQL, Redis, a Celery worker, and an S3-compatible object store (MinIO locally).

There are two supported paths:

Docker Compose (recommended) — every dependency runs in a container, so there are no conflicting local installs.
Manual / virtualenv — you run Django directly against a PostgreSQL and Redis you provide yourself.

Most contributors should use Docker Compose. Use the manual path only if you cannot run Docker, or you need to attach native tooling.

💡 Tip

The default branch for contributions is develop. Clone and base your work on it. See the contribution workflow for branching and PR conventions.

Docker Compose (recommended)

Prerequisites

[https://docs.docker.com/get-docker/ Docker]
Docker Compose (bundled with Docker Desktop)

The Compose stack runs the following containers:

Container	Role
`backend`	Care Django application (serves the API)
`db`	PostgreSQL database
`redis`	In-memory cache and Celery broker
`celery`	Background task worker
`minio`	S3-compatible object store (mimics AWS locally)

1. Build the images

make build

The first build pulls base images and installs dependencies, so it can take a while depending on your machine and network speed.

2. Start the stack

make up

This starts all containers in the background and waits for them to become healthy. Once it returns, the API is available at http://localhost:9000.

💡 Tip

To attach the VS Code debugger, set DJANGO_DEBUG=True in your .env file before starting the stack.

3. Seed data

Load the fixtures (base roles, permissions, and reference data) so the app is usable:

make load-fixtures

4. Create an admin user

docker compose exec backend python manage.py createsuperuser

Follow the prompts to set the username, email, and password. You can now sign in to the API and (with the frontend running) the web app.

Running tests

Run the full test suite:

make test

Run a single test file, class, or method by passing a dotted path:

make test path=<dotted.path>

Stopping and resetting

# Stop and remove containers, keeping your data volumes
make down

# Stop and remove containers AND their volumes (wipes the database)
make teardown

After changing dependencies or migrations

Whenever you update a Python dependency or add a migration that must run inside the container, rebuild the image without cache:

make re-build

📝 Note

make re-build rebuilds with --no-cache, so it is slower than make build. Use it specifically when a plain make up no longer reflects your dependency or migration changes.

Manual / virtualenv setup

Use this path only if you are not using Docker. You are responsible for running PostgreSQL and Redis yourself.

1. Provision PostgreSQL

Create a role and database. For example, in psql:

CREATE ROLE my_username LOGIN PASSWORD 'my_password';
CREATE DATABASE care WITH OWNER = my_username;

2. Create a virtual environment and install dependencies

python3 -m venv .venv
source .venv/bin/activate
pipenv sync --categories "packages dev-packages docs"

3. Configure environment

Put your database connection string in a .env file at the repository root:

DATABASE_URL=postgres://my_username:my_password@localhost:5432/care

Tell Django to read it:

export DJANGO_READ_DOT_ENV_FILE=true

4. Migrate and run

python manage.py migrate
python manage.py runserver

Seed data and create an admin user the same way as in the Docker path, but run the commands directly:

python manage.py load_fixtures
python manage.py createsuperuser

Run the test suite with:

python manage.py test

{{Note|title=macOS troubleshooting|1=If you installed PostgreSQL via [https://postgresapp.com/ Postgres.app], add its binaries to your PATH so psql and friends are found (adjust the version to match your install):

export PATH=$PATH:/Applications/Postgres.app/Contents/Versions/14/bin

If pipenv sync fails while building Pillow, install its native image libraries first:

brew install libjpeg libtiff little-cms2 openjpeg webp freetype harfbuzz fribidi
```}}


## Pre-commit hooks

Care uses [https://pre-commit.com/ pre-commit] to run linters and formatters before each commit. Install the hooks once after cloning:

```bash
pre-commit install

To run the hooks against only the files you have changed relative to develop:

pre-commit run --files $(git diff --name-only develop...HEAD)

Useful `make` targets

These targets are defined in the repository's Makefile and wrap the most common Docker Compose workflows.

Target	What it does
`make build`	Build the Docker images
`make re-build`	Rebuild the images with `--no-cache` (after dependency or migration changes)
`make up`	Start the stack in the background and wait until healthy
`make down`	Stop and remove containers, keeping volumes
`make teardown`	Stop and remove containers and volumes (wipes data)
`make load-fixtures`	Load seed/reference data into the database
`make migrate`	Apply database migrations
`make makemigrations`	Generate new migrations from model changes
`make test`	Run the test suite (pass `path=<dotted.path>` for one test)
`make logs`	Show logs for the stack
`make reset-and-setup`	Reset the database, then migrate and reload fixtures

Next steps

Set up the frontend to use the web app against this API.
Prefer a reproducible toolchain? See the Nix dev environment.
Ready to contribute? Read the contribution workflow.