feat: add Coolify deployment documentation (#39) #62
376
docs/COOLIFY_DEPLOYMENT.md
Normal file
376
docs/COOLIFY_DEPLOYMENT.md
Normal file
@@ -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! 🎉**
|
||||
210
docs/DEPLOYMENT_CHECKLIST.md
Normal file
210
docs/DEPLOYMENT_CHECKLIST.md
Normal file
@@ -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!
|
||||
Reference in New Issue
Block a user