Nix Development Environment for CARE¶

This document describes how to set up and use the Nix-based development environment for the CARE

Prerequisites¶

Install Nix: Follow the installation instructions at nixos.org or use the Determinate Systems installer:
```
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
Note: The Determinate Systems installer is preferred as it provides a cleaner installation process and hassle-free uninstallation from user machines.
Enable Flakes: Nix flakes should be enabled automatically with modern installers. If not, add to ~/.config/nix/nix.conf:
```
experimental-features = nix-command flakes
```

Optional - Install direnv: For automatic environment activation:

# On macOS with Homebrew
brew install direnv

# On Linux (varies by distribution)
sudo apt install direnv  # Ubuntu/Debian
sudo dnf install direnv  # Fedora

Quick Setup¶

For first-time setup, run the automated setup script:

./scripts/nix-dev-setup.sh

This script will:

Verify Nix installation
Set up the development environment
Install all Python dependencies
Start required services (PostgreSQL, Redis, MinIO)
Run database migrations
Optionally load sample data

Manual Setup¶

If you prefer manual setup or need to troubleshoot:

1. Enter Development Shell¶

nix develop

This will:

Install all required system packages
Set up environment variables
Make development commands available
Show a helpful welcome message

2. Install Python Dependencies¶

setup-dev

3. Start Services¶

start-services

This starts:

PostgreSQL on port 5432
Redis on port 6379
MinIO on port 9000 (console on 9001)

4. Set Up Database¶

migrate
load-fixtures  # Optional: load sample data

5. Start Complete Development Environment¶

Option A: Unified Start (Recommended)¶

rundev

This single command starts both the Django server and Celery worker together with proper migrations and setup.

Option B: Separate Services¶

# Terminal 1: Django server
runserver

# Terminal 2: Celery worker  
nix develop --command celery

The Django server will be available at http://localhost:9000

Available Commands¶

Once in the development shell (nix develop), you have access to these commands:

Service Management¶

start-services - Start PostgreSQL, Redis, and MinIO
stop-services - Stop background services only
kill-care - 🛑 Stop ALL development processes and services
healthcheck - Check application health

Development Server¶

rundev - 🚀 Start both API server and Celery worker (RECOMMENDED)
runserver - Start Django development server only
celery - Start Celery worker with beat scheduler only

Database Operations¶

migrate - Run database migrations
makemigrations [app] - Create new migrations
load-fixtures - Load sample data
dump-db - Backup database to care_db.dump
load-db - Restore database from care_db.dump
reset-db - Drop and recreate database

Django Management¶

manage <command> - Run any Django management command
manage shell - Django shell
manage collectstatic - Collect static files

Testing¶

test [path] - Run tests (with database reuse)
test-no-keep [path] - Run tests (fresh database)
test-coverage - Run tests with coverage report

Code Quality¶

ruff - Check and fix staged files
ruff-all - Check all Python files
ruff-fix-all - Fix all Python files

Initial Setup¶

setup-dev - Install dependencies and set up environment

Environment Variables¶

The development environment sets these variables automatically:

Database¶

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_HOST=localhost
POSTGRES_DB=care
DATABASE_URL=postgres://postgres:postgres@localhost:5432/care

Redis¶

REDIS_URL=redis://localhost:6379
CELERY_BROKER_URL=redis://localhost:6379/0

Django¶

DJANGO_DEBUG=true
DJANGO_SETTINGS_MODULE=config.settings.local

MinIO/S3¶

BUCKET_ENDPOINT=http://localhost:9100
BUCKET_KEY=minioadmin
BUCKET_SECRET=minioadmin

Service URLs¶

Django Application: http://localhost:9000
MinIO Console: http://localhost:9001 (admin: minioadmin/minioadmin)
PostgreSQL: localhost:5432 (postgres/postgres)
Redis: localhost:6379

Development Workflow¶

Daily Development¶

Quick Start (Recommended)¶

Start your session:

nix develop
start-services  # If not already running

Start the complete application:

rundev  # Starts both Django server and Celery worker together

Manual Start (Advanced)¶

Start your session:

nix develop
start-services  # If not already running

Start services separately:

# Terminal 1: Django server
runserver

# Terminal 2: Celery worker
nix develop --command celery

Make changes and test:

ruff-all          # Check code style
test              # Run tests
manage shell      # Interactive Django shell

Stop when done:

kill-care         # Stop all development processes

Working with Database¶

# Create and apply migrations
makemigrations
migrate

# Reset database if needed
stop-services
reset-db
start-services
migrate
load-fixtures

Debugging¶

Enable Django Debug Mode¶

Set ATTACH_DEBUGGER=true and use runserver to start with debugpy on port 9876.

Check Services¶

# Check if services are running
ps aux | grep -E 'postgres|redis|minio'

# View service logs
journalctl --user -f  # On systemd systems

Database Connection Issues¶

# Check PostgreSQL status
pg_ctl status -D ~/.local/share/postgres

# Restart PostgreSQL
stop-services
start-services

Troubleshooting¶

Common Issues¶

“Permission denied” errors:

# Ensure directories are writable
mkdir -p ~/.local/bin ~/.local/share/postgres ~/.local/share/minio

Services won’t start:

# Stop any conflicting processes
stop-services
# Check for processes using ports
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis
lsof -i :9000  # MinIO

Python dependencies issues:

# Stop everything first
kill-care
# Reinstall in clean environment
rm -rf .venv
setup-dev

Database connection refused:

# Wait for PostgreSQL to fully start
sleep 5
# Or check if initialization is complete
pg_ctl status -D ~/.local/share/postgres

Clean Reset¶

If you encounter persistent issues:

# Stop all processes and services
kill-care

# Clean up data directories
rm -rf ~/.local/share/postgres ~/.local/share/minio

# Exit and re-enter development shell
exit
nix develop

# Restart setup
setup-dev
start-services
migrate

Differences from Docker Setup¶

Advantages of Nix¶

Faster startup: No container overhead
Native performance: Direct system execution
Reproducible: Same environment across different machines
Integrated tooling: All tools available in single shell
Easier debugging: Direct access to processes and files

Key Differences¶

Services run directly on host (not in containers)
Data stored in ~/.local/share/ instead of Docker volumes
Environment variables set in shell instead of env files
All commands available directly (no docker compose exec)

Integration with Existing Workflow¶

The Nix setup coexists with Docker setup:

Makefile commands still work when using Docker
Same Python dependencies and versions
Same database schema and migrations
Compatible with existing CI/CD pipelines

Contributing¶

When adding new dependencies:

Python packages: Add to Pipfile and run setup-dev
System packages: Add to flake.nix buildInputs
Services: Update service management scripts in flake.nix
Environment variables: Add to envVars in flake.nix

Performance Tips¶

Use direnv: Automatically enter/exit development shell:
```
echo "use flake" > .envrc
direnv allow
```
Keep services running: Services persist between shell sessions
Use test database reuse: Default test command reuses database for speed
Parallel testing: Tests run in parallel by default
Clean shutdown: Use kill-care command to properly stop all processes

Security Notes¶

Services bind to localhost only (not accessible externally)
Default credentials are for development only
MinIO uses development keys (minioadmin/minioadmin)
Database has no password (local development only)

For production deployment, use the Docker setup with proper security configurations.