yourwillyourwish/DEPLOYMENT.md

🚀 Estate Platform Deployment Guide

Overview

This Next.js application is optimized for both local development and Coolify deployment with Traefik reverse proxy.

📦 Docker Image Stats

• Base Image: node:20-bookworm-slim
• Build Type: Multi-stage (deps → builder → runner)
• Final Size: ~245MB (optimized from 1.98GB)
• Output Mode: Next.js standalone

🏗️ Quick Start

Local Development

1. Copy environment file:

   cp .env.example .env
   # Ensure APP_PORT=3000 for local access
   

2. Start services:

   bash dc.sh
   

3. Access application:

   • Web: http://localhost:3000
   • Adminer: http://localhost:8080
   • Logs: docker compose logs -f web

Coolify Deployment

1. Push to Git repository

2. In Coolify dashboard:

   • Create new resource → Docker Compose
   • Point to your docker-compose.yml
   • Set environment variables in Coolify UI

3. Required Environment Variables:

   # Leave APP_PORT empty for Coolify (Traefik handles routing)
   APP_PORT=
   
   # Database
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=<secure-password>
   POSTGRES_DB=estate_platform
   
   # Redis
   REDIS_PASSWORD=<secure-password>
   
   # Auth
   BETTER_AUTH_SECRET=<32-char-secret>
   BETTER_AUTH_URL=https://your-domain.com
   
   # OAuth (optional)
   GOOGLE_CLIENT_ID=...
   GOOGLE_CLIENT_SECRET=...
   # ... other OAuth providers
   

4. Deploy: Coolify will read the Traefik labels and configure routing automatically

🔧 Configuration

Port Exposure

The APP_PORT environment variable controls port exposure:

# docker-compose.yml
ports:
  - "${APP_PORT:-3000}:3000"

• Local: APP_PORT=3000 (exposes port for localhost:3000)
• Coolify: APP_PORT= (empty - Traefik handles all routing)

Traefik Labels

These labels are read by Coolify/Traefik:

labels:
  - coolify.managed=true
  - traefik.enable=true
  - traefik.http.services.web.loadbalancer.server.port=3000

📁 Static Assets

Static files are served from /public/:

• Images: /images/ → access as /images/logo.png
• Fonts: /fonts/ → reference as /fonts/custom.woff2
• SEO: /robots.txt, /sitemap.xml (update domain!)
• PWA: /manifest.json (update theme/icons)
• Favicon: /favicon.ico (replace placeholder)

See public/README.md for usage examples.

🗄️ Database

Initial Credentials

Created by seed script:

• Admin: admin@ywyw.com / Dev1234#
• Customer: cust@ywyw.com / Dev1234#

Migrations

# Apply migrations
docker compose exec web npx prisma migrate deploy

# Generate Prisma Client
docker compose exec web npx prisma generate

# Reset database (CAUTION: Development only!)
docker compose exec web npx prisma migrate reset

🧹 Maintenance

Clean Docker Resources

# Full cleanup (stops containers, removes volumes)
bash docker-cleanup.sh

# Rebuild from scratch
bash dc.sh

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f web
docker compose logs -f postgres
docker compose logs -f redis

Update Dependencies

# Update npm packages
npm update

# Rebuild container
bash dc.sh

🔍 Troubleshooting

Port Already in Use

# Find process using port 3000
lsof -ti:3000

# Kill process
kill -9 $(lsof -ti:3000)

Build Failures

# Clear Docker build cache
docker builder prune -af

# Remove all containers and volumes
bash docker-cleanup.sh

# Rebuild
bash dc.sh

Database Connection Issues

# Check postgres health
docker compose ps postgres

# View postgres logs
docker compose logs postgres

# Connect to postgres directly
docker compose exec postgres psql -U postgres -d estate_platform

Static Files Not Serving

1. Verify files exist in public/ directory
2. Rebuild container: bash dc.sh
3. Check file is copied: docker compose exec web ls -la /app/public
4. Test access: curl http://localhost:3000/robots.txt

📊 Performance Tips

1. Image Optimization: Docker image is optimized to ~245MB using:

   • Multi-stage builds
   • Alpine base image
   • Next.js standalone output
   • Selective file copying

2. Database Connection Pooling:

   • Connection limit: 20
   • Pool timeout: 20s

3. Redis Caching: Enabled for session management

🔐 Security Checklist

• Change default database credentials
• Generate secure BETTER_AUTH_SECRET (32+ characters)
• Update Redis password
• Set NODE_ENV=production for deployment
• Configure OAuth redirect URIs correctly
• Enable HTTPS in production (Traefik handles this in Coolify)
• Review robots.txt rules
• Change default admin password after first login

📚 Documentation

• Quick Reference
• Public Assets
• Environment Variables
• Docker Compose
• Dockerfile

🆘 Support

For issues:

1. Check logs: docker compose logs -f
2. Verify environment variables: docker compose config
3. Check container health: docker compose ps
4. Review docs/ folder for detailed setup guides