webref/docs/development/nix-services.md

Nix-Based Development Services

This project uses pure Nix for all development services, avoiding Docker in favor of the project's tech stack philosophy.

Philosophy

As specified in the plan:

• Deployment: Nix Flakes (reproducible, declarative)
• Infrastructure: Nix-managed services
• No Docker dependency - everything runs through Nix

Services

PostgreSQL 16

• Port: 5432
• Database: webref
• User: webref (no password for local dev)
• Data: .dev-data/postgres/

MinIO (S3-compatible storage)

• API: http://localhost:9000
• Console: http://localhost:9001
• Credentials: minioadmin / minioadmin
• Bucket: webref (auto-created)
• Data: .dev-data/minio/

Quick Start

1. Enter Nix development environment

nix develop

2. Start services

./scripts/dev-services.sh start

This will:

• Initialize PostgreSQL database (first time)
• Start PostgreSQL on localhost:5432
• Start MinIO on localhost:9000
• Create the webref bucket
• Set up environment variables

3. Run application

# Terminal 1: Backend
cd backend
uvicorn app.main:app --reload

# Terminal 2: Frontend  
cd frontend
npm run dev

4. Access services

• Backend API: http://localhost:8000/docs
• Frontend: http://localhost:5173
• MinIO Console: http://localhost:9001
• PostgreSQL: psql -h localhost -U webref webref

Service Management

Commands

# Start all services
./scripts/dev-services.sh start

# Stop all services
./scripts/dev-services.sh stop

# Restart services
./scripts/dev-services.sh restart

# Check status
./scripts/dev-services.sh status

# View logs
./scripts/dev-services.sh logs

# Reset all data (destructive!)
./scripts/dev-services.sh reset

Environment Variables

After starting services, these variables are automatically set:

DATABASE_URL=postgresql://webref@localhost:5432/webref
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

Data Storage

All development data is stored in .dev-data/ (gitignored):

.dev-data/
├── postgres/    # PostgreSQL database files
│   └── logfile  # PostgreSQL logs
└── minio/       # MinIO object storage
    └── minio.log # MinIO logs

To reset everything:

./scripts/dev-services.sh reset

Production Deployment

For production, services are managed through NixOS modules:

# See nixos/dev-services.nix for the service configuration
# Deploy with: nixos-rebuild switch --flake .#webref

Production configuration includes:

• Proper authentication (not trust-based)
• Persistent data volumes
• Systemd service management
• Automatic service startup
• Log rotation

Why Not Docker?

1. Consistency with deployment: Production uses NixOS, development should match
2. Reproducibility: Nix ensures identical environments everywhere
3. Declarative: All dependencies and services defined in flake.nix
4. No container overhead: Native processes are faster
5. Simpler stack: One tool (Nix) instead of two (Nix + Docker)

Troubleshooting

PostgreSQL won't start

# Check if another instance is running
pg_isready -h localhost -p 5432

# Check the logs
./scripts/dev-services.sh logs

# Reset and try again
./scripts/dev-services.sh reset
./scripts/dev-services.sh start

MinIO won't start

# Check if port 9000 is in use
lsof -i :9000

# Check the logs
./scripts/dev-services.sh logs

# Kill any existing MinIO processes
pkill -f minio
./scripts/dev-services.sh start

Services running but app can't connect

# Verify services are running
./scripts/dev-services.sh status

# Check environment variables
echo $DATABASE_URL
echo $MINIO_ENDPOINT

# Manually test connections
psql -h localhost -U webref webref -c "SELECT version();"
curl http://localhost:9000/minio/health/live

CI/CD

GitHub Actions CI also uses Nix for consistency:

# See .github/workflows/ci.yml
# Services are provided as GitHub Actions service containers
# but could also use nix-based test services

Migration from Docker

If you previously used docker-compose.dev.yml, remove it:

# Stop Docker services (if running)
docker-compose -f docker-compose.dev.yml down -v

# Use Nix services instead
./scripts/dev-services.sh start

All data formats are compatible - you can migrate data if needed by dumping from Docker PostgreSQL and restoring to Nix PostgreSQL.