pantry/docs/COOLIFY_DEPLOYMENT.md

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
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

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:

# 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

curl https://pantry.yourdomain.com/api/health

Expected response:

{
  "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:

   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:

   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:

# 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

# 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:

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:

# 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:

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! 🎉