phase 5

docs/development/nix-services.md

@@ -0,0 +1,212 @@
+# 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
+
+```bash
+nix develop
+```
+
+### 2. Start services
+
+```bash
+./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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+./scripts/dev-services.sh reset
+```
+
+## Production Deployment
+
+For production, services are managed through NixOS modules:
+
+```nix
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```yaml
+# 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:
+
+```bash
+# 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.
+