196 lines
4.3 KiB
Markdown
196 lines
4.3 KiB
Markdown
# Deployment Guide
|
|
|
|
## Prerequisite
|
|
|
|
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
|