View source for Contributing/Local development/Nix development environment

{{Doc header
|type=guide
|domain=contributing
|title=Nix development environment
|order=3
}}

Nix is an alternative to Docker Compose for backend development. Instead of running PostgreSQL, Redis, and MinIO inside containers, the Nix dev shell installs pinned versions of those services (and Python, ruff, and the build toolchain) from the Nix store and runs them directly on your host. Service data lives in a project-local <code>.nix-data/</code> directory.

If you would rather use the standard Docker-based workflow, see the [[Contributing/Local development/Backend setup|backend setup guide]].

{{Note|1=This environment is for backend (<code>care</code>) development. It targets macOS and non-NixOS Linux — the automated setup script intentionally refuses to run on NixOS, which should use NixOS-specific configuration instead.}}

== Prerequisites ==

<ol style="list-style-type: decimal;">
<li><p>'''Install Nix.''' The Determinate Systems installer is preferred — it provides a cleaner install and hassle-free uninstallation:</p>
<syntaxhighlight lang="bash">curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install</syntaxhighlight></li>
<li><p>'''Enable flakes.''' Modern installers enable flakes automatically. If yours did not, add the following to <code>~/.config/nix/nix.conf</code>:</p>
<syntaxhighlight lang="text">experimental-features = nix-command flakes</syntaxhighlight></li>
<li><p>'''Optional — install direnv''' for automatic shell activation when you <code>cd</code> into the repo:</p>
<syntaxhighlight lang="bash"># macOS (Homebrew)
brew install direnv

# Linux (varies by distribution)
sudo apt install direnv   # Ubuntu/Debian
sudo dnf install direnv   # Fedora</syntaxhighlight>
<p>Then, from the repo root:</p>
<syntaxhighlight lang="bash">echo "use flake" > .envrc
direnv allow</syntaxhighlight></li></ol>

== Automated setup ==

For a first-time setup, run the setup script from the repo root:

<syntaxhighlight lang="bash">./scripts/nix-dev-setup.sh</syntaxhighlight>
The script checks that Nix is installed and flakes are enabled, creates the Python virtual environment and installs dependencies, starts the services (PostgreSQL, Redis, MinIO), runs migrations, and optionally loads sample fixtures.

== Quick start (manual) ==

To set things up by hand, enter the dev shell and run the in-shell commands:

<syntaxhighlight lang="bash">nix develop
setup-dev
start-services
rundev</syntaxhighlight>
This enters the development environment, installs Python dependencies into a <code>.venv</code>, starts the background services, runs migrations, and launches the unified development server (Django API plus Celery worker).

{{Tip|1=Background services persist between shell sessions. On later days you usually only need <code>nix develop</code>, then <code>start-services</code> (if not already running), then <code>rundev</code>.}}

== In-shell commands ==

Once you are inside the dev shell (<code>nix develop</code>), these commands are on your <code>PATH</code>:

{| class="wikitable"
|-
! Group
! Command
! Description
|-
| Services
| <code>start-services</code>
| Start PostgreSQL, Redis, and MinIO
|-
| Services
| <code>stop-services</code>
| Stop the background services only
|-
| Services
| <code>kill-care</code>
| Stop all development processes and services
|-
| Server
| <code>rundev</code>
| Start the API server and Celery worker together (recommended)
|-
| Server
| <code>runserver</code>
| Start the Django development server only
|-
| Server
| <code>celery</code>
| Start the Celery worker with beat scheduler only
|-
| Database
| <code>migrate</code>
| Run database migrations
|-
| Database
| <code>load-fixtures</code>
| Load sample data
|-
| Database
| <code>reset-db</code>
| Drop and recreate the database
|-
| Testing
| <code>test</code>
| Run the test suite (reuses the database)
|-
| Testing
| <code>test-coverage</code>
| Run tests and produce a coverage report
|-
| Quality
| <code>ruff</code>
| Lint and fix staged Python files
|-
| Quality
| <code>ruff-all</code>
| Lint all Python files
|}

{{Note|1=Additional helpers are available in the shell, including <code>makemigrations</code>, <code>manage &lt;command&gt;</code>, <code>dump-db</code>, <code>load-db</code>, <code>clean-data</code>, <code>healthcheck</code>, <code>test-no-keep</code>, and <code>ruff-fix-all</code>. The dev shell prints the full list when you enter it.}}

== Service URLs ==

After <code>start-services</code> and <code>rundev</code> are up:

{| class="wikitable"
|-
! Service
! URL / address
! Notes
|-
| Django application
| http://localhost:9000
| API and admin
|-
| MinIO console
| http://localhost:9001
| S3-compatible object storage UI
|-
| PostgreSQL
| <code>localhost:5432</code>
| Database
|-
| Redis
| <code>localhost:6379</code>
| Cache and Celery broker
|}

{{Info|1=Default development credentials (for example the MinIO and database logins) are set automatically by the dev shell and are intended for local use only. Services bind to localhost and are not reachable externally.}}

== How it differs from Docker ==

The Nix workflow produces the same database schema, migrations, and Python dependency versions as the Docker setup — the two can coexist. The main differences:

* '''Services run on the host''', not inside containers, so there is no container overhead and startup is faster.
* '''Data lives in <code>.nix-data/</code>''' (<code>postgres/</code>, <code>redis/</code>, <code>minio/</code>) instead of Docker volumes. This directory is added to <code>.gitignore</code> automatically.
* '''Commands run directly''' in the shell — there is no <code>docker compose exec</code> indirection.
* '''Versions are pinned''' by the flake (for example Python 3.13 and PostgreSQL 15 from the Nix store), so the toolchain is reproducible across machines.

{{Related}}