diff --git a/docs/COOLIFY_DEPLOYMENT.md b/docs/COOLIFY_DEPLOYMENT.md new file mode 100644 index 0000000..8dea8f1 --- /dev/null +++ b/docs/COOLIFY_DEPLOYMENT.md @@ -0,0 +1,376 @@ +# Coolify Deployment Guide + +## Prerequisites + +- Coolify instance running (self-hosted or cloud) +- Gitea repository accessible to Coolify +- Supabase project (cloud or self-hosted) +- Domain name (optional, for production) + +## Deployment Steps + +### 1. Prepare Supabase + +#### Option A: Supabase Cloud + +1. Sign in to [supabase.com](https://supabase.com) +2. Create new project (or use existing) +3. Run migrations: + - Go to SQL Editor + - Copy/paste each file from `supabase/migrations/` + - Run in order: 001_, 002_, 003_, etc. +4. Get credentials: + - Project Settings → API + - Copy Project URL + - Copy `anon` / `public` key + +#### Option B: Self-Hosted Supabase + +```bash +cd supabase +docker-compose up -d +# Wait for services to start +docker-compose ps +``` + +Migrations run automatically from `supabase/migrations/` directory. + +### 2. Add Resource in Coolify + +1. Log in to Coolify +2. Click "New Resource" +3. Select "Docker Compose" +4. Choose deployment source: + - **Git Repository** (recommended) + - Public Git Repository + - Docker Image + +### 3. Configure Git Repository + +If using Git source: + +1. **Repository URL:** + ``` + https://gitea.jeanlucmakiola.de/pantry-app/pantry.git + ``` + +2. **Branch:** `main` (or `develop` for staging) + +3. **Docker Compose File:** `docker-compose.prod.yml` + +4. **Build Path:** Leave empty (uses root) + +### 4. Set Environment Variables + +In Coolify → Environment Variables, add: + +```bash +# Required +NUXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co +NUXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here + +# Optional +NODE_ENV=production +HOST=0.0.0.0 +PORT=3000 +``` + +**Security Note:** Never commit `.env` files with real credentials! + +### 5. Configure Domain (Optional) + +1. In Coolify → Domains +2. Add your domain: `pantry.yourdomain.com` +3. Coolify auto-provisions SSL with Let's Encrypt +4. DNS: Point A record to Coolify server IP + +### 6. Deploy + +1. Click "Deploy" button +2. Watch build logs +3. Wait for "Deployed successfully" message + +Expected deploy time: 2-5 minutes + +### 7. Verify Deployment + +#### Health Check + +```bash +curl https://pantry.yourdomain.com/api/health +``` + +Expected response: +```json +{ + "status": "ok", + "timestamp": "2026-02-25T00:00:00.000Z", + "uptime": 123.456 +} +``` + +#### PWA Check + +1. Visit app in browser +2. Open DevTools → Application → Manifest +3. Verify manifest loads +4. Check Service Worker is registered + +#### Functionality Test + +- [ ] Homepage loads +- [ ] Can sign up / sign in +- [ ] Can view inventory +- [ ] Can add item +- [ ] PWA install prompt appears +- [ ] Offline mode works + +## Troubleshooting + +### Build Fails + +**Check build logs in Coolify:** + +Common issues: +- Missing dependencies → Check package.json +- npm/node version mismatch → Use Node 20 Alpine +- Out of memory → Increase Coolify resource limits + +### Container Won't Start + +**Check runtime logs in Coolify:** + +Common issues: +- Missing environment variables +- Port conflict (use 3000) +- Supabase connection timeout + +### Supabase Connection Error + +1. Verify Supabase URL is correct (no trailing slash) +2. Check anon key is valid +3. Test Supabase API directly: + ```bash + curl https://your-project.supabase.co/rest/v1/ + ``` +4. Check Supabase RLS policies allow access + +### SSL Certificate Issues + +Coolify should auto-provision Let's Encrypt cert: +- Ensure domain points to correct IP +- Check DNS propagation (can take 48h) +- Verify port 80/443 open on firewall + +### App Loads but No Data + +1. Check browser console for errors +2. Verify Supabase connection in Network tab +3. Check RLS policies in Supabase +4. Verify migrations ran successfully + +## Continuous Deployment + +### Auto-Deploy on Push + +1. In Coolify → Settings → Webhooks +2. Copy webhook URL +3. In Gitea → Repo → Settings → Webhooks +4. Add webhook: + - URL: [Coolify webhook URL] + - Events: Push events + - Branch: main (or develop) + +Now every git push triggers auto-deployment! + +### Manual Deploy + +In Coolify interface: +1. Click "Deploy Latest" button +2. Or use Coolify API: + ```bash + curl -X POST https://coolify.example.com/api/deploy/[resource-id] \ + -H "Authorization: Bearer [your-token]" + ``` + +## Monitoring + +### View Logs + +Coolify Dashboard → Logs tab + +Real-time logs: +```bash +# If SSH access to Coolify host +docker logs -f [container-name] +``` + +### Resource Usage + +Coolify shows: +- CPU usage +- Memory usage +- Network traffic +- Storage + +### Uptime Monitoring + +Recommended external services: +- UptimeRobot (free tier) +- BetterStack +- Freshping + +Monitor: `https://pantry.yourdomain.com/api/health` + +## Rollback + +### To Previous Version + +1. In Coolify → Deployments +2. Click on previous successful deployment +3. Click "Redeploy" + +### Using Git Tags + +```bash +# Tag current release +git tag -a v0.1.0 -m "MVP Release" +git push origin v0.1.0 + +# Rollback by changing branch in Coolify +# Or deploy specific tag +``` + +## Performance Optimization + +### Resource Limits + +In docker-compose.prod.yml: +```yaml +deploy: + resources: + limits: + memory: 512M + cpus: '1.0' +``` + +Adjust based on traffic. + +### CDN (Recommended) + +1. Add domain to Cloudflare +2. Set DNS proxy (orange cloud) +3. Enable caching rules +4. Set SSL to "Full (strict)" + +**Result:** ~50% faster load times globally + +### Database Connection Pooling + +If self-hosting Supabase: +- Use PgBouncer (included in Supabase) +- Set max connections: 20-50 + +## Security Checklist + +Before going live: + +- [ ] HTTPS enabled (automatic with Coolify) +- [ ] Environment variables set (not in repo) +- [ ] Supabase RLS policies enabled +- [ ] Strong database passwords +- [ ] Firewall configured (only 80/443 open) +- [ ] Supabase auth configured +- [ ] Regular backups enabled +- [ ] Monitoring alerts set up + +## Backup Strategy + +### Database Backups + +**Supabase Cloud:** Automatic daily backups + +**Self-hosted:** +```bash +# Manual backup +docker exec supabase-db pg_dump -U postgres > backup.sql + +# Automated (cron) +0 2 * * * /path/to/backup-script.sh +``` + +### Volume Backups + +Coolify persistent volumes: +```bash +docker run --rm \ + -v coolify_pantry_data:/data \ + -v $(pwd):/backup \ + ubuntu tar czf /backup/pantry-backup.tar.gz /data +``` + +## Staging Environment + +Recommended setup: + +**Production:** +- Branch: `main` +- Domain: `pantry.yourdomain.com` +- Supabase: Production project + +**Staging:** +- Branch: `develop` +- Domain: `staging.pantry.yourdomain.com` +- Supabase: Separate test project + +In Coolify, create two resources pointing to different branches. + +## Cost Estimate + +**Coolify (self-hosted):** +- VPS: $5-10/month (Hetzner, Digital Ocean) +- Domain: $10-15/year +- **Total:** ~$8/month + +**Supabase Cloud:** +- Free tier: 500MB database, 1GB file storage +- Pro tier: $25/month (more resources) + +**Total Cost:** $8-33/month for full stack + +## Support + +**Coolify:** +- Docs: https://coolify.io/docs +- Discord: https://discord.gg/coolify + +**Pantry:** +- Issues: https://gitea.jeanlucmakiola.de/pantry-app/pantry/issues +- Discussions: TBD + +## Post-Deployment Checklist + +After first deployment: + +- [ ] Health check passes +- [ ] Can access homepage +- [ ] Can sign up / sign in +- [ ] Can add inventory item +- [ ] PWA installs correctly +- [ ] Offline mode works +- [ ] SSL certificate valid +- [ ] Monitoring alerts configured +- [ ] Backup strategy in place +- [ ] Team notified of URL + +## Next Steps + +1. Run E2E tests (see E2E_TESTING.md) +2. Monitor for 24-48 hours +3. Announce to users +4. Set up analytics (optional) +5. Plan first iteration + +--- + +**Congratulations! Your app is live! 🎉** diff --git a/docs/DEPLOYMENT_CHECKLIST.md b/docs/DEPLOYMENT_CHECKLIST.md new file mode 100644 index 0000000..1fe8e1e --- /dev/null +++ b/docs/DEPLOYMENT_CHECKLIST.md @@ -0,0 +1,210 @@ +# Deployment Checklist + +Use this checklist to ensure a smooth deployment to production or staging. + +## Pre-Deployment + +### Code Quality +- [ ] All tests passing (E2E_TESTING.md) +- [ ] No critical bugs open +- [ ] Code reviewed and approved +- [ ] CHANGELOG.md updated +- [ ] Version tagged in git + +### Database +- [ ] Migrations tested locally +- [ ] Migrations run on staging +- [ ] Seed data prepared (if needed) +- [ ] Backup created +- [ ] RLS policies verified + +### Configuration +- [ ] Environment variables documented +- [ ] .env.production.example updated +- [ ] Secrets not in repository +- [ ] Docker files tested locally +- [ ] Health check endpoint working + +### Documentation +- [ ] DEPLOYMENT.md reviewed +- [ ] README.md up to date +- [ ] API changes documented +- [ ] Known issues documented + +## Deployment + +### Coolify Setup +- [ ] Resource created in Coolify +- [ ] Git repository connected +- [ ] Branch configured (main/develop) +- [ ] docker-compose.prod.yml path set +- [ ] Environment variables added +- [ ] Domain configured (optional) +- [ ] SSL enabled + +### Supabase Setup +- [ ] Project created +- [ ] Migrations run +- [ ] RLS policies enabled +- [ ] Auth providers configured +- [ ] Storage buckets created +- [ ] API keys copied + +### Build & Deploy +- [ ] Triggered deployment +- [ ] Build logs checked (no errors) +- [ ] Container started successfully +- [ ] Health check passes + +## Post-Deployment Verification + +### Health Checks +- [ ] `/api/health` returns 200 OK +- [ ] Homepage loads +- [ ] Auth works (sign up/in) +- [ ] Database connection works + +### PWA +- [ ] Manifest loads correctly +- [ ] Service worker registers +- [ ] Install prompt appears +- [ ] Offline mode works +- [ ] Icons display correctly + +### Functionality +- [ ] Can create account +- [ ] Can sign in +- [ ] Can add inventory item +- [ ] Can edit item +- [ ] Can delete item +- [ ] Can add tags +- [ ] Can scan barcode (if implemented) + +### Performance +- [ ] Page load < 3s +- [ ] Lighthouse score > 90 (PWA) +- [ ] No console errors +- [ ] No network errors + +### Cross-Browser +- [ ] Chrome (desktop) +- [ ] Firefox (desktop) +- [ ] Safari (desktop) +- [ ] Chrome (mobile) +- [ ] Safari (iOS) + +## Monitoring + +### Setup +- [ ] Uptime monitoring configured +- [ ] Error tracking enabled (optional) +- [ ] Log aggregation set up +- [ ] Alerts configured +- [ ] Metrics dashboard created (optional) + +### Checks +- [ ] CPU usage normal +- [ ] Memory usage normal +- [ ] Disk space sufficient +- [ ] No error spikes + +## Security + +### Verification +- [ ] HTTPS enabled +- [ ] SSL certificate valid +- [ ] No credentials exposed +- [ ] Firewall configured +- [ ] Supabase RLS enabled +- [ ] Strong admin passwords + +### Compliance +- [ ] Privacy policy added (if required) +- [ ] Terms of service added (if required) +- [ ] Cookie notice (if applicable) +- [ ] GDPR compliance (if EU users) + +## Communication + +### Team +- [ ] Deployment announced +- [ ] Access details shared +- [ ] Rollback plan communicated +- [ ] Support plan established + +### Users +- [ ] Announcement prepared +- [ ] Migration guide ready (if needed) +- [ ] Support channels available +- [ ] Feedback mechanism in place + +## Backup & Recovery + +### Backups +- [ ] Database backup verified +- [ ] Volume backup taken +- [ ] Backup restore tested +- [ ] Backup schedule configured + +### Disaster Recovery +- [ ] Rollback plan documented +- [ ] Emergency contacts listed +- [ ] Recovery time objective (RTO) defined +- [ ] Recovery point objective (RPO) defined + +## Post-Launch (24-48h) + +### Monitoring +- [ ] Check logs for errors +- [ ] Review uptime metrics +- [ ] Analyze user behavior +- [ ] Check resource usage + +### Optimization +- [ ] Identify slow queries +- [ ] Optimize heavy assets +- [ ] Review caching strategy +- [ ] Tune resource limits + +### Feedback +- [ ] Collect user feedback +- [ ] Log issues found +- [ ] Prioritize fixes +- [ ] Plan next iteration + +## Sign-Off + +**Deployed by:** ___________________ +**Date:** ___________________ +**Environment:** Production / Staging +**Version:** ___________________ +**Status:** ✅ Success / ⚠️ Issues / ❌ Failed + +**Notes:** +_____________________________________________ +_____________________________________________ +_____________________________________________ + +**Next Review:** ___________________ + +--- + +## Rollback Criteria + +Trigger rollback if: +- [ ] Critical bug discovered +- [ ] Data loss occurring +- [ ] Service unavailable > 15 min +- [ ] Security vulnerability found +- [ ] Performance degraded > 50% + +**Rollback Procedure:** +1. In Coolify → Previous deployment → Redeploy +2. Or: `git revert` and redeploy +3. Notify team and users +4. Investigate root cause +5. Fix and redeploy + +--- + +**Remember:** It's better to delay than to deploy broken code. Take your time with this checklist!