213 lines
4.4 KiB
Markdown
213 lines
4.4 KiB
Markdown
# 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.
|
|
|