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:

```bash
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:

```env
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:
   ```bash
   bun run db:push
   ```

### Option B: Using Docker Exec

SSH into your Coolify server and run:
```bash
docker exec -it <container-name> bun run db:push
```

Find the container name with:
```bash
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:
   ```bash
   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:
```bash
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:

```env
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:
```bash
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)