nani

docs/deployment.md

@@ -0,0 +1,187 @@
+# Deployment & Migrations Guide
+
+This document covers database migrations and deployment workflows for SimbaRAG.
+
+## Migration Workflow
+
+Migrations are managed by [Aerich](https://github.com/tortoise/aerich), the migration tool for Tortoise ORM.
+
+### Key Principles
+
+1. **Generate migrations in Docker** - Aerich needs database access to detect schema changes
+2. **Migrations auto-apply on startup** - Both `startup.sh` and `startup-dev.sh` run `aerich upgrade`
+3. **Commit migrations to git** - Migration files must be in the repo for production deploys
+
+### Generating a New Migration
+
+#### Development (Recommended)
+
+With `docker-compose.dev.yml`, your local `services/raggr` directory is synced to the container. Migrations generated inside the container appear on your host automatically.
+
+```bash
+# 1. Start the dev environment
+docker compose -f docker-compose.dev.yml up -d
+
+# 2. Generate migration (runs inside container, syncs to host)
+docker compose -f docker-compose.dev.yml exec raggr aerich migrate --name describe_your_change
+
+# 3. Verify migration was created
+ls services/raggr/migrations/models/
+
+# 4. Commit the migration
+git add services/raggr/migrations/
+git commit -m "Add migration: describe_your_change"
+```
+
+#### Production Container
+
+For production, migration files are baked into the image. You must generate migrations in dev first.
+
+```bash
+# If you need to generate a migration from production (not recommended):
+docker compose exec raggr aerich migrate --name describe_your_change
+
+# Copy the file out of the container
+docker cp $(docker compose ps -q raggr):/app/migrations/models/ ./services/raggr/migrations/
+```
+
+### Applying Migrations
+
+Migrations apply automatically on container start via the startup scripts.
+
+**Manual application (if needed):**
+
+```bash
+# Dev
+docker compose -f docker-compose.dev.yml exec raggr aerich upgrade
+
+# Production
+docker compose exec raggr aerich upgrade
+```
+
+### Checking Migration Status
+
+```bash
+# View applied migrations
+docker compose exec raggr aerich history
+
+# View pending migrations
+docker compose exec raggr aerich heads
+```
+
+### Rolling Back
+
+```bash
+# Downgrade one migration
+docker compose exec raggr aerich downgrade
+
+# Downgrade to specific version
+docker compose exec raggr aerich downgrade -v 1
+```
+
+## Deployment Workflows
+
+### Development
+
+```bash
+# Start with watch mode (auto-restarts on file changes)
+docker compose -f docker-compose.dev.yml up
+
+# Or with docker compose watch (requires Docker Compose v2.22+)
+docker compose -f docker-compose.dev.yml watch
+```
+
+The dev environment:
+- Syncs `services/raggr/` to `/app` in the container
+- Rebuilds frontend on changes
+- Auto-applies migrations on startup
+
+### Production
+
+```bash
+# Build and deploy
+docker compose build raggr
+docker compose up -d
+
+# View logs
+docker compose logs -f raggr
+
+# Verify migrations applied
+docker compose exec raggr aerich history
+```
+
+### Fresh Deploy (New Database)
+
+On first deploy with an empty database, `startup-dev.sh` runs `aerich init-db` instead of `aerich upgrade`. This creates all tables from the current models.
+
+For production (`startup.sh`), ensure the database exists and run:
+
+```bash
+# If aerich table doesn't exist yet
+docker compose exec raggr aerich init-db
+
+# Or if migrating from existing schema
+docker compose exec raggr aerich upgrade
+```
+
+## Troubleshooting
+
+### "No migrations found" on startup
+
+The `migrations/models/` directory is empty or not copied into the image.
+
+**Fix:** Ensure migrations are committed and the Dockerfile copies them:
+```dockerfile
+COPY migrations ./migrations
+```
+
+### Migration fails with "relation already exists"
+
+The database has tables but aerich doesn't know about them (fresh aerich setup on existing DB).
+
+**Fix:** Fake the initial migration:
+```bash
+# Mark initial migration as applied without running it
+docker compose exec raggr aerich upgrade --fake
+```
+
+### Model changes not detected
+
+Aerich compares models against the last migration's state. If state is out of sync:
+
+```bash
+# Regenerate migration state (dangerous - review carefully)
+docker compose exec raggr aerich migrate --name fix_state
+```
+
+### Database connection errors
+
+Ensure PostgreSQL is healthy before running migrations:
+
+```bash
+# Check postgres status
+docker compose ps postgres
+
+# Wait for postgres then run migrations
+docker compose exec raggr bash -c "sleep 5 && aerich upgrade"
+```
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `services/raggr/pyproject.toml` | Aerich config (`[tool.aerich]` section) |
+| `services/raggr/migrations/models/` | Migration files |
+| `services/raggr/startup.sh` | Production startup (runs `aerich upgrade`) |
+| `services/raggr/startup-dev.sh` | Dev startup (runs `aerich upgrade` or `init-db`) |
+| `services/raggr/app.py` | Contains `TORTOISE_CONFIG` |
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Generate migration | `docker compose -f docker-compose.dev.yml exec raggr aerich migrate --name name` |
+| Apply migrations | `docker compose exec raggr aerich upgrade` |
+| View history | `docker compose exec raggr aerich history` |
+| Rollback | `docker compose exec raggr aerich downgrade` |
+| Fresh init | `docker compose exec raggr aerich init-db` |