# Placebo.mk Docker Setup

## Overview
Complete Docker configuration for Placebo.mk - a Macedonian news site with sarcastic tone. Includes both development and production setups.

## Architecture
- **Frontend**: TanStack (React 19) + Vite + Tailwind CSS
- **Backend**: NestJS + TypeORM
- **CMS**: Strapi
- **Database**: PostgreSQL (production), SQLite (development)
- **Reverse Proxy**: Nginx (production)

## Quick Start

### Development Environment (Hot Reload)
```bash
# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# Services available at:
# Frontend: http://localhost:5173
# Backend API: http://localhost:3000
# CMS Admin: http://localhost:1337/admin
# PostgreSQL: localhost:5432
```

### Production Environment (Local Testing)
```bash
# Start production environment
docker-compose up -d

# Services available at:
# Frontend: http://localhost:3001
# Backend API: http://localhost:3000
# CMS: http://localhost:1337
```

### Test Everything
```bash
# Run comprehensive test
chmod +x scripts/test-docker.sh
./scripts/test-docker.sh
```

## Docker Files Structure

### Production Dockerfiles
- `backend/Dockerfile` - NestJS API with Node.js 20 Alpine
- `frontend/Dockerfile` - React app built with Vite, served by Nginx
- `cms/cms/Dockerfile` - Strapi CMS with PostgreSQL support
- `frontend/nginx.conf` - Nginx configuration for frontend

### Development Dockerfiles
- `backend/Dockerfile.dev` - Development with hot reload
- `frontend/Dockerfile.dev` - Development with Vite dev server
- `cms/cms/Dockerfile.dev` - Strapi development mode

### Docker Compose Files
- `docker-compose.yml` - Production setup with all services
- `docker-compose.dev.yml` - Development setup with volume mounts

## Services

### 1. PostgreSQL Database
- **Image**: `postgres:16-alpine`
- **Port**: 5432
- **Database**: `placebo_db`
- **User**: `placebo_user`
- **Password**: `placebo_password`
- **Volume**: `postgres_data` (persistent storage)

### 2. Backend API (NestJS)
- **Production Port**: 3000
- **Development Port**: 3000 (hot reload)
- **Health Check**: `GET /health`
- **Environment**: See `backend/.env.example`

### 3. Frontend (TanStack React)
- **Production Port**: 3001 (via Nginx)
- **Development Port**: 5173 (Vite dev server)
- **Build Tool**: Vite
- **Environment**: See `frontend/.env.example`

### 4. CMS (Strapi)
- **Port**: 1337
- **Admin**: `/admin`
- **Health Check**: `GET /_health`
- **Environment**: See `cms/cms/.env.example`

### 5. Nginx (Production Only)
- **Port**: 80
- **Configuration**: `frontend/nginx.conf`
- **Features**: SSL, compression, security headers, React Router support

## Environment Variables

### Backend (.env)
```bash
NODE_ENV=production
DATABASE_TYPE=postgres
DATABASE_HOST=postgres
DATABASE_PORT=5432
DATABASE_USERNAME=placebo_user
DATABASE_PASSWORD=placebo_password
DATABASE_NAME=placebo_db
JWT_SECRET=your-jwt-secret-key-change-in-production
CORS_ORIGIN=http://localhost:5173,http://localhost:3001
```

### Frontend (.env)
```bash
NODE_ENV=production
VITE_API_URL=http://localhost:3000
VITE_CMS_URL=http://localhost:1337
```

### CMS (.env)
```bash
NODE_ENV=production
DATABASE_CLIENT=postgres
DATABASE_HOST=postgres
DATABASE_PORT=5432
DATABASE_NAME=placebo_db
DATABASE_USERNAME=placebo_user
DATABASE_PASSWORD=placebo_password
JWT_SECRET=your-jwt-secret-key-change-in-production
```

## Common Commands

### Development
```bash
# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Stop development
docker-compose -f docker-compose.dev.yml down

# Rebuild development images
docker-compose -f docker-compose.dev.yml build
```

### Production (Local Testing)
```bash
# Start production environment
docker-compose up -d

# View logs
docker-compose logs -f

# Stop production
docker-compose down

# Rebuild production images
docker-compose build
```

### Database Operations
```bash
# Access PostgreSQL shell
docker-compose exec postgres psql -U placebo_user -d placebo_db

# Backup database
docker-compose exec postgres pg_dump -U placebo_user placebo_db > backup.sql

# Restore database
docker-compose exec -T postgres psql -U placebo_user placebo_db < backup.sql
```

### Service Management
```bash
# Restart specific service
docker-compose restart backend
docker-compose restart frontend
docker-compose restart cms

# View service status
docker-compose ps

# View resource usage
docker-compose stats
```

## Health Checks

All services include health checks:

### Backend
```bash
curl http://localhost:3000/health
```

### CMS
```bash
curl http://localhost:1337/_health
```

### Frontend
```bash
curl http://localhost:3001
```

### PostgreSQL
```bash
docker-compose exec postgres pg_isready -U placebo_user -d placebo_db
```

## Database Migration

### SQLite to PostgreSQL Migration
Detailed migration plan in `scripts/migrate-to-postgres.md`

```bash
# Export SQLite data
sqlite3 backend/data.db .dump > backend-data.sql

# Transform for PostgreSQL
python scripts/transform-sqlite-to-postgres.py backend-data.sql > backend-postgres.sql

# Import to PostgreSQL
docker-compose exec -T postgres psql -U placebo_user placebo_db < backend-postgres.sql
```

## Troubleshooting

### Common Issues

#### 1. Port Conflicts
```bash
# Check what's using port 3000
sudo lsof -i :3000

# Or use different ports in docker-compose.yml
```

#### 2. Docker Build Failures
```bash
# Clear Docker cache
docker system prune -a

# Rebuild with no cache
docker-compose build --no-cache
```

#### 3. Database Connection Issues
```bash
# Check PostgreSQL logs
docker-compose logs postgres

# Test connection from backend
docker-compose exec backend node -e "console.log('Testing DB connection...')"
```

#### 4. Permission Issues
```bash
# Fix volume permissions
sudo chown -R $USER:$USER .

# Rebuild containers
docker-compose down && docker-compose up -d
```

### Debug Commands
```bash
# Shell into container
docker-compose exec backend sh
docker-compose exec frontend sh
docker-compose exec cms sh

# View container details
docker-compose exec backend env
docker-compose exec frontend env

# Check network connectivity
docker-compose exec backend curl http://postgres:5432
docker-compose exec frontend curl http://backend:3000/health
```

## Deployment to Coolify

### 1. Prepare for Production
```bash
# Update environment variables for production
cp backend/.env.example backend/.env.production
cp frontend/.env.example frontend/.env.production
cp cms/cms/.env.example cms/cms/.env.production

# Build production images
docker-compose build

# Test locally
docker-compose up -d
./scripts/test-docker.sh
```

### 2. Coolify Configuration
1. Connect GitHub repository to Coolify
2. Create three applications:
   - Frontend (from `/frontend`)
   - Backend (from `/backend`)
   - CMS (from `/cms/cms`)
3. Configure environment variables
4. Set up PostgreSQL database
5. Configure domains and SSL

### 3. Database Migration
1. Export production SQLite data
2. Transform for PostgreSQL
3. Import to Coolify PostgreSQL
4. Verify data integrity

## Performance Optimization

### Frontend
- Nginx gzip compression enabled
- Static asset caching (1 year)
- Security headers configured
- React Router support

### Backend
- Health checks every 30 seconds
- Connection pooling with PostgreSQL
- CORS configured for frontend domains

### Database
- PostgreSQL connection pooling
- Regular backups via volumes
- Health checks with `pg_isready`

## Security

### Implemented Security Features
1. **Non-root users**: All containers run as non-root
2. **Health checks**: Automatic service monitoring
3. **Environment variables**: Secrets stored in .env files
4. **Network isolation**: Services on internal network
5. **Security headers**: X-Frame-Options, CSP, etc.
6. **SSL ready**: Nginx configured for HTTPS

### Security Best Practices
1. Never commit `.env` files to Git
2. Use strong passwords for PostgreSQL
3. Regular security updates
4. Monitor Docker logs
5. Backup database regularly

## Monitoring

### Built-in Monitoring
```bash
# View container logs
docker-compose logs -f

# Check container status
docker-compose ps

# Monitor resource usage
docker-compose stats

# View health check status
docker inspect --format='{{.State.Health.Status}}' placebo-backend
```

### Custom Monitoring
Add to `docker-compose.yml`:
```yaml
monitoring:
  image: prom/prometheus
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
```

## Backup and Recovery

### Database Backup
```bash
# Daily backup script
docker-compose exec postgres pg_dump -U placebo_user placebo_db > backup-$(date +%Y%m%d).sql

# Compress backup
gzip backup-$(date +%Y%m%d).sql
```

### Volume Backup
```bash
# Backup PostgreSQL volume
docker run --rm -v postgres_data:/source -v $(pwd)/backups:/backup alpine tar czf /backup/postgres-$(date +%Y%m%d).tar.gz -C /source .
```

### Recovery
```bash
# Restore database
docker-compose exec -T postgres psql -U placebo_user placebo_db < backup.sql

# Restore volume
docker run --rm -v postgres_data:/target -v $(pwd)/backups:/backup alpine tar xzf /backup/postgres-backup.tar.gz -C /target
```

## Contributing

### Adding New Services
1. Create Dockerfile in service directory
2. Add service to `docker-compose.yml`
3. Configure environment variables
4. Add health check
5. Test locally
6. Update documentation

### Updating Dependencies
```bash
# Rebuild with updated dependencies
docker-compose build --no-cache

# Update package.json in mounted volumes
docker-compose exec backend npm update
docker-compose exec frontend npm update
docker-compose exec cms npm update
```

## Support

### Documentation
- `DEPLOYMENT.md` - Complete deployment guide
- `scripts/migrate-to-postgres.md` - Database migration plan
- `AGENTS.md` - Development guidelines

### Troubleshooting Resources
- Docker Documentation: https://docs.docker.com
- PostgreSQL Documentation: https://www.postgresql.org/docs
- Strapi Documentation: https://docs.strapi.io
- Coolify Documentation: https://coolify.io/docs

### Macedonian Resources
- Local hosting providers
- Macedonian domain registration
- GDPR compliance for Macedonian users