From ca8929a9162d3f7009ca347994c2466b6b900a22 Mon Sep 17 00:00:00 2001 From: Yves Gugger Date: Mon, 15 Dec 2025 10:30:19 +0100 Subject: [PATCH] docs: Add comprehensive deployment guide --- DEPLOY.md | 414 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 414 insertions(+) create mode 100644 DEPLOY.md diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..4987095 --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,414 @@ +# Pounce Deployment Guide + +## Server Information +- **Server IP**: `10.42.0.73` +- **User**: `user` +- **Git Remote**: `git.6bit.ch` (10.13.12.81) +- **Frontend Port**: 3000 +- **Backend Port**: 8000 +- **Public URL**: https://pounce.ch + +## Automated Deployment (Recommended) + +### Using the Deploy Script + +The `deploy.sh` script handles zero-downtime deployments automatically: + +```bash +# Full deployment (commit + push + deploy) +./deploy.sh "Your commit message" + +# Frontend only +./deploy.sh -f "Frontend changes" + +# Backend only +./deploy.sh -b "Backend changes" + +# Quick sync without git operations +./deploy.sh -q + +# Force deploy (skips safety checks) +./deploy.sh --force "Force deploy" +``` + +### What the Script Does + +1. **Git Operations** (unless `-q` flag): + - Commits all changes with your message + - Pushes to `git.6bit.ch` + +2. **Syncing Files**: + - Uses `rsync` to transfer only changed files to server + - Preserves timestamps and permissions + - Frontend: syncs to `~/pounce/frontend/` + - Backend: syncs to `~/pounce/backend/` + +3. **Building**: + - Frontend: `npm run build` (creates optimized production build) + - Backend: `pip install -r requirements.txt` (updates dependencies) + +4. **Restarting Services**: + - Gracefully restarts Next.js and Uvicorn + - Zero downtime using `./start.sh` + +## Manual Deployment + +### Step 1: Commit & Push Local Changes + +```bash +cd /Users/yvesgugger/Documents/Projekte/pounce + +# Check status +git status + +# Add all changes +git add -A + +# Commit +git commit -m "Your descriptive commit message" + +# Push to git.6bit.ch +git push +``` + +### Step 2: SSH into Server & Pull Changes + +```bash +# Connect to server +sshpass -p "user" ssh user@10.42.0.73 + +# Navigate to project +cd ~/pounce + +# Pull latest changes +git pull +``` + +### Step 3: Frontend Deployment + +```bash +# Navigate to frontend +cd ~/pounce/frontend + +# Install dependencies (if package.json changed) +npm install + +# Build production version +npm run build + +# The build creates a .next folder with optimized static files +``` + +### Step 4: Backend Deployment + +```bash +# Navigate to backend +cd ~/pounce/backend + +# Activate virtual environment +source venv/bin/activate + +# Install/update dependencies (if requirements.txt changed) +pip install -r requirements.txt + +# Deactivate venv +deactivate +``` + +### Step 5: Restart Services + +```bash +# Navigate to project root +cd ~/pounce + +# Stop running services +pkill -f 'uvicorn' +pkill -f 'next start' + +# Start services using start script +./start.sh +``` + +## Start Script (`start.sh`) + +The `start.sh` script handles: +- Stopping existing processes on ports 8000 and 3000 +- Starting the backend (Uvicorn) with proper settings +- Starting the frontend (Next.js) in production mode +- Health checks for both services +- Logging to `backend.log` and `frontend.log` + +### Manual Service Management + +```bash +# Check running processes +ps aux | grep uvicorn +ps aux | grep next + +# View logs +tail -f ~/pounce/backend/backend.log +tail -f ~/pounce/frontend/frontend.log + +# Check ports +lsof -i :8000 # Backend +lsof -i :3000 # Frontend +``` + +## Environment Configuration + +### Backend `.env` (~/pounce/backend/.env) + +```env +DATABASE_URL=postgresql://user:password@localhost:5432/domainwatch +SECRET_KEY=your-secret-key-here +STRIPE_SECRET_KEY=sk_live_xxx +STRIPE_PUBLISHABLE_KEY=pk_live_xxx +STRIPE_WEBHOOK_SECRET=whsec_xxx +ZOHO_SMTP_USER=noreply@pounce.ch +ZOHO_SMTP_PASSWORD=xxx +GOOGLE_CLIENT_ID=xxx +GOOGLE_CLIENT_SECRET=xxx +GITHUB_CLIENT_ID=xxx +GITHUB_CLIENT_SECRET=xxx +site_url=https://pounce.ch +``` + +### Frontend `.env.local` (~/pounce/frontend/.env.local) + +```env +NEXT_PUBLIC_API_URL=https://pounce.ch/api/v1 +NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xxx +NEXT_PUBLIC_POSTHOG_KEY=phc_xxx +NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com +``` + +## Nginx Configuration + +Nginx acts as reverse proxy on the server: + +```nginx +# Frontend (Next.js) +location / { + proxy_pass http://localhost:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; +} + +# Backend (FastAPI) +location /api { + proxy_pass http://localhost:8000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; +} +``` + +## Troubleshooting + +### Frontend won't start + +```bash +# Check for port conflicts +lsof -i :3000 + +# Check build errors +cd ~/pounce/frontend +npm run build + +# Check logs +tail -f ~/pounce/frontend/frontend.log +``` + +### Backend won't start + +```bash +# Check for port conflicts +lsof -i :8000 + +# Test backend manually +cd ~/pounce/backend +source venv/bin/activate +uvicorn app.main:app --host 0.0.0.0 --port 8000 + +# Check logs +tail -f ~/pounce/backend/backend.log +``` + +### Database issues + +```bash +# Check PostgreSQL status +sudo systemctl status postgresql + +# Connect to database +psql -U user -d domainwatch + +# Check migrations +cd ~/pounce/backend +alembic current +alembic upgrade head +``` + +### SSL Certificate issues + +```bash +# Check certificate expiry +sudo certbot certificates + +# Renew certificates +sudo certbot renew + +# Restart Nginx +sudo systemctl restart nginx +``` + +## Health Checks + +```bash +# Backend health +curl http://localhost:8000/health + +# Frontend health +curl -I http://localhost:3000 + +# Full stack check via public URL +curl https://pounce.ch +curl https://pounce.ch/api/health +``` + +## Rollback Procedure + +If deployment fails: + +```bash +# On server +cd ~/pounce + +# See recent commits +git log --oneline -10 + +# Rollback to previous commit +git reset --hard + +# Rebuild +cd frontend && npm run build +cd ../backend && source venv/bin/activate && pip install -r requirements.txt + +# Restart +cd .. && ./start.sh +``` + +## Monitoring & Maintenance + +### Log Rotation + +Logs are in: +- `~/pounce/backend/backend.log` +- `~/pounce/frontend/frontend.log` + +Set up log rotation to prevent disk space issues: + +```bash +# Create logrotate config +sudo nano /etc/logrotate.d/pounce +``` + +``` +/home/user/pounce/backend/backend.log { + daily + rotate 14 + compress + delaycompress + notifempty + create 0640 user user +} + +/home/user/pounce/frontend/frontend.log { + daily + rotate 14 + compress + delaycompress + notifempty + create 0640 user user +} +``` + +### Cron Jobs + +Check scheduled tasks: + +```bash +crontab -l +``` + +Common cron jobs for Pounce: +- Domain scraping +- Health checks +- Database cleanup +- Backup scripts + +## Backup & Recovery + +### Database Backup + +```bash +# Manual backup +pg_dump -U user domainwatch > backup_$(date +%Y%m%d_%H%M%S).sql + +# Restore from backup +psql -U user domainwatch < backup_20250101_120000.sql +``` + +### Code Backup + +All code is backed up on `git.6bit.ch`. To clone fresh: + +```bash +git clone user@10.13.12.81:yvg/pounce.git +``` + +## Security Notes + +- Server uses SSH key authentication (password: `user` for development) +- SSL certificates via Let's Encrypt (auto-renewal) +- Database credentials in `.env` files (not committed to git) +- Stripe webhooks require signing secret verification +- OAuth secrets must match registered redirect URIs + +## Quick Reference + +```bash +# Deploy everything +./deploy.sh "message" + +# Frontend only +./deploy.sh -f "message" + +# Backend only +./deploy.sh -b "message" + +# Quick sync (no git) +./deploy.sh -q + +# Check logs +ssh user@10.42.0.73 'tail -f ~/pounce/backend/backend.log' + +# Restart services +ssh user@10.42.0.73 'cd ~/pounce && ./start.sh' + +# Check health +curl https://pounce.ch/api/health +``` + +## Support + +For issues or questions, check: +1. Application logs (`backend.log`, `frontend.log`) +2. Nginx logs (`/var/log/nginx/error.log`) +3. PostgreSQL logs (`/var/log/postgresql/`) +4. System logs (`journalctl -xe`) +