Gallus_Pub/backend/DEPLOYMENT.md

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

cd backend
flyctl apps create gallus-cms-backend

2. Create Volume for Data (SQLite DB + Git Workspace)

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

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

flyctl deploy

5. Initialize Database

After first deployment, SSH into the container and run migrations:

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

flyctl logs

Check Status

flyctl status

SSH into Container

flyctl ssh console

Scale App

flyctl scale count 2

View Secrets

flyctl secrets list

Update a Secret

flyctl secrets set KEY=VALUE

Restart App

flyctl apps restart

Monitoring

Health Check

curl https://gallus-cms-backend.fly.dev/health

View Metrics

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:

git pull
flyctl deploy

Rollback

To rollback to previous version:

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