Admin: Add Navbox contributing (via update-page on MediaWiki MCP Server)

2026-07-06T04:21:49Z

Add Navbox contributing (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:51, 6 July 2026
Line 191:		Line 191:
	* Prefer a reproducible toolchain? See the [[Contributing/Local development/Nix development environment\|Nix dev environment]].		* Prefer a reproducible toolchain? See the [[Contributing/Local development/Nix development environment\|Nix dev environment]].
	* Ready to contribute? Read the [[Contributing/Contribution workflow\|contribution workflow]].		* Ready to contribute? Read the [[Contributing/Contribution workflow\|contribution workflow]].

			{{Navbox contributing}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T23:07:12Z

OHC identity seed

New page

{{Doc header
|type=guide
|domain=contributing
|title=Backend setup
|order=1
}}

This page walks you through running the Care backend ([<nowiki/>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|1=The default branch for contributions is <code>develop</code>. Clone and base your work on it. See the [[Contributing/Contribution workflow|contribution workflow]] for branching and PR conventions.}}

== Docker Compose (recommended) ==

=== Prerequisites ===

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

The Compose stack runs the following containers:

{| class="wikitable"
|-
! Container
! Role
|-
| <code>backend</code>
| Care Django application (serves the API)
|-
| <code>db</code>
| PostgreSQL database
|-
| <code>redis</code>
| In-memory cache and Celery broker
|-
| <code>celery</code>
| Background task worker
|-
| <code>minio</code>
| S3-compatible object store (mimics AWS locally)
|}

=== 1. Build the images ===

<syntaxhighlight lang="bash">make build</syntaxhighlight>
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 ===

<syntaxhighlight lang="bash">make up</syntaxhighlight>
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 http://localhost:9000].

{{Tip|1=To attach the VS Code debugger, set <code>DJANGO_DEBUG=True</code> in your <code>.env</code> file before starting the stack.}}

=== 3. Seed data ===

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

<syntaxhighlight lang="bash">make load-fixtures</syntaxhighlight>
=== 4. Create an admin user ===

<syntaxhighlight lang="bash">docker compose exec backend python manage.py createsuperuser</syntaxhighlight>
Follow the prompts to set the username, email, and password. You can now sign in to the API and (with the [[Contributing/Local development/Frontend setup|frontend]] running) the web app.

=== Running tests ===

Run the full test suite:

<syntaxhighlight lang="bash">make test</syntaxhighlight>
Run a single test file, class, or method by passing a dotted <code>path</code>:

<syntaxhighlight lang="bash">make test path=<dotted.path></syntaxhighlight>
=== Stopping and resetting ===

<syntaxhighlight lang="bash"># Stop and remove containers, keeping your data volumes
make down

# Stop and remove containers AND their volumes (wipes the database)
make teardown</syntaxhighlight>
=== 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:

<syntaxhighlight lang="bash">make re-build</syntaxhighlight>
{{Note|1=<code>make re-build</code> rebuilds with <code>--no-cache</code>, so it is slower than <code>make build</code>. Use it specifically when a plain <code>make up</code> 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 <code>psql</code>:

<syntaxhighlight lang="sql">CREATE ROLE my_username LOGIN PASSWORD 'my_password';
CREATE DATABASE care WITH OWNER = my_username;</syntaxhighlight>
=== 2. Create a virtual environment and install dependencies ===

<syntaxhighlight lang="bash">python3 -m venv .venv
source .venv/bin/activate
pipenv sync --categories "packages dev-packages docs"</syntaxhighlight>
=== 3. Configure environment ===

Put your database connection string in a <code>.env</code> file at the repository root:

<pre class="env">DATABASE_URL=postgres://my_username:my_password@localhost:5432/care</pre>
Tell Django to read it:

<syntaxhighlight lang="bash">export DJANGO_READ_DOT_ENV_FILE=true</syntaxhighlight>
=== 4. Migrate and run ===

<syntaxhighlight lang="bash">python manage.py migrate
python manage.py runserver</syntaxhighlight>
Seed data and create an admin user the same way as in the Docker path, but run the commands directly:

<syntaxhighlight lang="bash">python manage.py load_fixtures
python manage.py createsuperuser</syntaxhighlight>
Run the test suite with:

<syntaxhighlight lang="bash">python manage.py test</syntaxhighlight>
{{Note|title=macOS troubleshooting|1=If you installed PostgreSQL via [<nowiki/>https://postgresapp.com/ Postgres.app], add its binaries to your <code>PATH</code> so <code>psql</code> and friends are found (adjust the version to match your install):

<syntaxhighlight lang="bash">export PATH=$PATH:/Applications/Postgres.app/Contents/Versions/14/bin</syntaxhighlight>
If <code>pipenv sync</code> fails while building Pillow, install its native image libraries first:

<syntaxhighlight lang="bash">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</syntaxhighlight>
To run the hooks against only the files you have changed relative to <code>develop</code>:

<syntaxhighlight lang="bash">pre-commit run --files $(git diff --name-only develop...HEAD)</syntaxhighlight>
== Useful <code>make</code> targets ==

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

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

== Next steps ==

* Set up the [[Contributing/Local development/Frontend setup|frontend]] to use the web app against this API.
* Prefer a reproducible toolchain? See the [[Contributing/Local development/Nix development environment|Nix dev environment]].
* Ready to contribute? Read the [[Contributing/Contribution workflow|contribution workflow]].

{{Related}}

Contributing/Local development/Backend setup - Revision history

Admin: Add Navbox contributing (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed