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**:
   ```bash
   cp .env.example .env
   # Ensure APP_PORT=3000 for local access
   ```

2. **Start services**:
   ```bash
   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**:
   ```bash
   # 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:

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

```yaml
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](public/README.md) for usage examples.

## 🗄️ Database

### Initial Credentials

Created by seed script:
- **Admin**: admin@ywyw.com / Dev1234#
- **Customer**: cust@ywyw.com / Dev1234#

### Migrations

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

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

# Rebuild from scratch
bash dc.sh
```

### View Logs

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

```bash
# Update npm packages
npm update

# Rebuild container
bash dc.sh
```

## 🔍 Troubleshooting

### Port Already in Use

```bash
# Find process using port 3000
lsof -ti:3000

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

### Build Failures

```bash
# Clear Docker build cache
docker builder prune -af

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

# Rebuild
bash dc.sh
```

### Database Connection Issues

```bash
# 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](QUICK_REFERENCE.md)
- [Public Assets](public/README.md)
- [Environment Variables](.env.example)
- [Docker Compose](docker-compose.yml)
- [Dockerfile](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/](docs/) folder for detailed setup guides