wishlist/wishlist-app/COOLIFY_DEPLOYMENT.md

Coolify Deployment Guide

This guide will help you deploy the Wishlist app to Coolify using Docker.

Prerequisites

• Coolify instance running (self-hosted or cloud)
• PostgreSQL database (can be created in Coolify)
• Git repository (GitHub, GitLab, or Gitea)

Step 1: Push Code to Git Repository

If you haven't already, push your code to a Git repository:

git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repo-url>
git push -u origin main

Step 2: Set Up PostgreSQL in Coolify

1. Go to your Coolify dashboard
2. Click + New Resource → Database → PostgreSQL
3. Configure:
   • Name: wishlist-db
   • PostgreSQL Version: 16 (or latest)
   • Click Create
4. Once created, note down the connection details:
   • Host: (internal hostname, e.g., wishlist-db)
   • Port: 5432
   • Database: postgres (or create a new database)
   • Username: postgres
   • Password: (auto-generated or set your own)

Step 3: Create the Application in Coolify

1. Click + New Resource → Application
2. Select your Git source (GitHub, GitLab, etc.)
3. Choose your repository
4. Configure the application:
   • Branch: main (or your default branch)
   • Build Pack: Docker
   • Port: 3000
   • Dockerfile Location: ./Dockerfile (default)

Step 4: Configure Environment Variables

In the Coolify application settings, go to Environment Variables and add:

DATABASE_URL=postgresql://postgres:YOUR_PASSWORD@wishlist-db:5432/postgres
NODE_ENV=production
PORT=3000

Important: Replace YOUR_PASSWORD with the actual password from Step 2.

Getting the Database Connection String

If you created the database in Coolify, you can find the connection string in:

1. Go to your database resource
2. Click on Connection String or Environment Variables
3. Copy the DATABASE_URL or construct it as:

   postgresql://[USERNAME]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
   

Step 5: Configure Health Check (Optional but Recommended)

In Coolify application settings:

1. Go to Health Check
2. Set:
   • Path: /
   • Port: 3000
   • Interval: 30s

Step 6: Deploy

1. Click Deploy button in Coolify
2. Monitor the build logs
3. Wait for the deployment to complete

The build process will:

• Install dependencies with Bun
• Build the SvelteKit application
• Create a production-ready Docker image
• Start the application on port 3000

Step 7: Run Database Migrations

After the first deployment, you need to set up the database schema. You have two options:

Option A: Using Coolify Terminal (Recommended)

1. Go to your application in Coolify
2. Click Terminal or Console
3. Run:

   bun run db:push
   

Option B: Using Docker Exec

SSH into your Coolify server and run:

docker exec -it <container-name> bun run db:push

Find the container name with:

docker ps | grep wishlist

Step 8: Access Your Application

1. In Coolify, go to your application
2. You should see the generated domain (e.g., wishlist-xyz.coolify.io)
3. Optionally, configure a custom domain in Domains settings

Visit your domain and your wishlist app should be running! 🎉

Updating the Application

For future updates:

1. Push changes to your Git repository:

   git add .
   git commit -m "Your changes"
   git push
   

2. In Coolify, click Deploy to rebuild and redeploy

Or enable Auto Deploy in Coolify settings to deploy automatically on push.

Troubleshooting

Build Fails

Check the build logs in Coolify for specific errors.

Common issues:

• Missing environment variables
• Wrong Node/Bun version
• Database connection issues during build

Application Crashes

1. Check application logs in Coolify
2. Verify DATABASE_URL is correct
3. Ensure database is running and accessible
4. Check if migrations were run

Database Connection Errors

Error: Connection refused

Solutions:

• Verify the database hostname (use internal Coolify network name)
• Check database is running: Go to database resource in Coolify
• Ensure application and database are in the same network/project
• Verify credentials are correct

Port Issues

Error: Port 3000 already in use

Solution:

• Coolify handles port mapping automatically
• Don't change the PORT environment variable unless needed
• Check if another service is using port 3000

Migration Errors

Error: relation "wishlists" does not exist

Solution: Run the database migration:

docker exec -it <container-name> bun run db:push

Environment-Specific Configuration

Using Multiple Databases

For different environments (staging/production):

1. Create separate database resources in Coolify
2. Use different DATABASE_URL for each environment
3. Deploy to different branches or applications

SSL/TLS for Database

If using an external PostgreSQL with SSL:

DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require

Advanced Configuration

Custom Domain

1. In Coolify, go to application → Domains
2. Click Add Domain
3. Enter your domain (e.g., wishlist.yourdomain.com)
4. Configure DNS:
   • Add A record pointing to your Coolify server IP
   • Or CNAME pointing to your Coolify domain
5. Coolify will automatically configure SSL with Let's Encrypt

Scaling

To scale your application:

1. In Coolify, adjust resources:
   • CPU Limit
   • Memory Limit
2. Consider using a managed PostgreSQL service for better performance
3. Enable multiple replicas (if your Coolify setup supports it)

Backup Database

In Coolify database settings:

1. Go to Backups
2. Configure automatic backups
3. Set backup frequency and retention

Or manually backup:

docker exec -it <db-container> pg_dump -U postgres postgres > backup.sql

Production Checklist

Before going live:

• Database backups configured
• Custom domain configured with SSL
• Environment variables set correctly
• Database migrations run successfully
• Health checks configured
• Application logs monitored
• Test wishlist creation and reservation flow
• Test on mobile devices

Support

If you encounter issues:

1. Check Coolify documentation: https://coolify.io/docs
2. Review application logs in Coolify dashboard
3. Verify all environment variables are set
4. Ensure database is accessible from the application

Next Steps

• Set up monitoring (Coolify has built-in monitoring)
• Configure alerts for downtime
• Set up automated backups
• Consider CDN for static assets (if needed)