# 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.