feat(backend): initial setup for cms backend service

backend/DEPLOYMENT.md

@@ -0,0 +1,195 @@
+# Deployment Guide
+
+## Prerequisites
+
+1. Fly.io CLI installed: `curl -L https://fly.io/install.sh | sh`
+2. Fly.io account: `flyctl auth login`
+3. Gitea OAuth app configured at git.bookageek.ch
+4. Gitea Personal Access Token for git operations
+
+## Initial Setup
+
+### 1. Create Fly.io App
+
+```bash
+cd backend
+flyctl apps create gallus-cms-backend
+```
+
+### 2. Create Volume for Data (SQLite DB + Git Workspace)
+
+```bash
+flyctl volumes create gallus_data --size 2 --region ams
+```
+
+This volume will store:
+- SQLite database at `/app/data/gallus_cms.db`
+- Git workspace at `/app/data/workspace`
+
+### 3. Set Secrets
+
+```bash
+flyctl secrets set \
+  GITEA_CLIENT_ID="<your-gitea-oauth-client-id>" \
+  GITEA_CLIENT_SECRET="<your-gitea-oauth-client-secret>" \
+  GIT_TOKEN="<your-gitea-personal-access-token>" \
+  JWT_SECRET="$(openssl rand -base64 32)" \
+  SESSION_SECRET="$(openssl rand -base64 32)" \
+  GIT_REPO_URL="https://git.bookageek.ch/yourusername/Gallus_Pub.git" \
+  GIT_USER_NAME="Gallus CMS" \
+  GIT_USER_EMAIL="cms@galluspub.ch" \
+  GITEA_REDIRECT_URI="https://gallus-cms-backend.fly.dev/api/auth/callback" \
+  FRONTEND_URL="https://cms.galluspub.ch" \
+  CORS_ORIGIN="https://cms.galluspub.ch" \
+  GITEA_ALLOWED_USERS="sabrina,raphael"
+```
+
+### 4. Deploy
+
+```bash
+flyctl deploy
+```
+
+### 5. Initialize Database
+
+After first deployment, SSH into the container and run migrations:
+```bash
+flyctl ssh console
+cd /app
+node dist/index.js  # Start once to create the database file
+# Then exit (Ctrl+C) and run migrations
+npm run db:migrate
+exit
+```
+
+Or simply let the app run - the database will be created automatically on first start.
+
+## Gitea OAuth Configuration
+
+Update your Gitea OAuth application redirect URI to include:
+```
+https://gallus-cms-backend.fly.dev/api/auth/callback
+```
+
+## Useful Commands
+
+### View Logs
+```bash
+flyctl logs
+```
+
+### Check Status
+```bash
+flyctl status
+```
+
+### SSH into Container
+```bash
+flyctl ssh console
+```
+
+### Scale App
+```bash
+flyctl scale count 2
+```
+
+### View Secrets
+```bash
+flyctl secrets list
+```
+
+### Update a Secret
+```bash
+flyctl secrets set KEY=VALUE
+```
+
+### Restart App
+```bash
+flyctl apps restart
+```
+
+## Monitoring
+
+### Health Check
+```bash
+curl https://gallus-cms-backend.fly.dev/health
+```
+
+### View Metrics
+```bash
+flyctl dashboard
+```
+
+## Troubleshooting
+
+### Deployment Fails
+- Check logs: `flyctl logs`
+- Verify all secrets are set: `flyctl secrets list`
+- Ensure Docker builds locally: `docker build -t test .`
+
+### OAuth Not Working
+- Verify GITEA_REDIRECT_URI matches Gitea settings exactly
+- Check CORS_ORIGIN includes frontend domain
+- Review logs for authentication errors
+
+### Git Push Fails
+- Verify GIT_TOKEN has correct permissions
+- Check GIT_REPO_URL is accessible
+- Ensure workspace volume is mounted
+
+### Database Issues
+- Verify DATABASE_PATH is set correctly
+- Check volume is mounted: `flyctl ssh console` then `ls -la /app/data`
+- Verify database file permissions
+- Run migrations if needed: `flyctl ssh console` then `npm run db:migrate`
+
+## Cost Optimization
+
+Current configuration uses:
+- `shared-cpu-1x` with 512MB RAM
+- Auto-suspend when idle
+- 2GB volume for SQLite database + git workspace
+
+Estimated cost: ~$5-10/month (no separate database cost with SQLite!)
+
+## Updating
+
+To deploy updates:
+```bash
+git pull
+flyctl deploy
+```
+
+## Rollback
+
+To rollback to previous version:
+```bash
+flyctl releases list
+flyctl releases rollback <version-number>
+```
+
+## Environment Variables
+
+All sensitive environment variables should be set as Fly.io secrets (not in fly.toml):
+
+Note: DATABASE_PATH and GIT_WORKSPACE_DIR are set in fly.toml as they're not sensitive.
+- `GITEA_CLIENT_ID` - OAuth client ID
+- `GITEA_CLIENT_SECRET` - OAuth client secret
+- `GIT_TOKEN` - Gitea personal access token
+- `JWT_SECRET` - JWT signing secret
+- `SESSION_SECRET` - Session cookie secret
+- `GIT_REPO_URL` - Full git repository URL
+- `GITEA_REDIRECT_URI` - OAuth callback URL
+- `FRONTEND_URL` - Frontend application URL
+- `CORS_ORIGIN` - Allowed CORS origin
+- `GITEA_ALLOWED_USERS` - Comma-separated list of allowed usernames
+
+## Security Checklist
+
+- [ ] All secrets set and not exposed in logs
+- [ ] HTTPS enforced (fly.toml: force_https = true)
+- [ ] CORS configured correctly
+- [ ] GITEA_ALLOWED_USERS whitelist configured
+- [ ] Database backups enabled
+- [ ] Health checks configured
+- [ ] Monitoring and alerts set up