# Placebo.mk Deployment Guide

## Overview
This document outlines the deployment strategy for Placebo.mk - a Macedonian news site with sarcastic tone, built with TanStack (React), NestJS, and Strapi CMS.

## Architecture
- **Frontend**: TanStack (React 19 + Query + Router) + Vite + Tailwind CSS
- **Backend**: NestJS + TypeORM + PostgreSQL (migrated from SQLite)
- **CMS**: Strapi with PostgreSQL
- **Deployment**: Docker + Coolify on VPS

## Deployment Options

### Option 1: Coolify + VPS (Recommended)
**Pros**: Self-hosted, cost-effective, full control, Macedonian audience optimized  
**Cons**: Requires server management

### Option 2: Platform-as-a-Service
**Pros**: No server management, automatic scaling  
**Cons**: More expensive, less control

## Coolify + VPS Deployment

### Phase 1: Infrastructure Setup

#### 1.1 VPS Requirements
- **Provider**: Hetzner (Germany) or DigitalOcean (Amsterdam)
- **Specs**: 4GB RAM, 2 vCPU, 80GB SSD (€10-15/month)
- **OS**: Ubuntu 22.04 LTS
- **Domain**: placebo.mk

#### 1.2 Install Coolify
```bash
# On VPS
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
```

Coolify automatically installs:
- Docker and Docker Compose
- Traefik reverse proxy
- Let's Encrypt SSL
- Admin interface

#### 1.3 Domain Configuration
1. Purchase `placebo.mk` domain
2. Configure DNS A records:
   - `placebo.mk` → VPS IP
   - `www.placebo.mk` → VPS IP
   - `api.placebo.mk` → VPS IP
   - `cms.placebo.mk` → VPS IP

### Phase 2: Database Migration

#### 2.1 PostgreSQL Setup
Create PostgreSQL database via Coolify one-click apps:
- Database name: `placebomk`
- Username: `placebo`
- Password: Generate secure password

#### 2.2 Migrate from SQLite
Detailed migration plan available in `scripts/migrate-to-postgres.md`

Run migration script:
```bash
# Test migration locally first
docker-compose up -d postgres
./scripts/migrate-data.sh

# Production migration
cd backend
npm run migrate:postgres
```

#### 2.3 Migration Strategy
1. **Development**: Use SQLite for local development
2. **Staging**: PostgreSQL with test data
3. **Production**: PostgreSQL with migrated data
4. **Backup**: Maintain SQLite backups during transition

### Phase 3: Application Deployment

#### 3.1 Connect GitHub Repository
1. Connect your GitHub repo to Coolify
2. Create three applications:
   - `placebo-frontend` (from `/frontend`)
   - `placebo-backend` (from `/backend`)
   - `placebo-cms` (from `/cms/cms`)

#### 3.2 Configure Applications

**Backend Configuration:**
- **Build Command**: `npm run build`
- **Start Command**: `npm run start:prod`
- **Port**: 3000
- **Environment Variables**:
  ```
  NODE_ENV=production
  DATABASE_URL=postgresql://placebo:PASSWORD@postgres:5432/placebomk
  CORS_ORIGIN=https://placebo.mk
  JWT_SECRET=your-secure-jwt-secret
  ```

**Frontend Configuration:**
- **Build Command**: `npm run build`
- **Output Directory**: `dist`
- **Environment Variables**:
  ```
  VITE_API_URL=https://api.placebo.mk/api/v1
  VITE_STRAPI_URL=https://cms.placebo.mk
  ```

**CMS Configuration:**
- **Build Command**: `npm run build`
- **Start Command**: `npm run start`
- **Port**: 1337
- **Environment Variables**:
  ```
  DATABASE_CLIENT=postgres
  DATABASE_HOST=postgres
  DATABASE_PORT=5432
  DATABASE_NAME=strapi
  DATABASE_USERNAME=placebo
  DATABASE_PASSWORD=PASSWORD
  ```

#### 3.3 Configure Domains in Coolify
- `placebo.mk` → Frontend application
- `api.placebo.mk` → Backend API
- `cms.placebo.mk` → Strapi CMS admin

### Phase 4: Security Configuration

#### 4.1 Environment Variables
Store sensitive data in Coolify environment variables:
- Database passwords
- JWT secrets
- API keys
- Strapi secrets

#### 4.2 SSL Certificates
Coolify automatically:
- Requests Let's Encrypt certificates
- Configures HTTPS redirect
- Auto-renews certificates

#### 4.3 Security Headers
Configure in Coolify:
- HSTS enabled
- CSP headers
- X-Frame-Options
- X-Content-Type-Options

### Phase 5: Monitoring & Backup

#### 5.1 Monitoring
- **Coolify built-in monitoring**: Resource usage, uptime
- **Application logs**: Access via Coolify UI
- **Health checks**: Configure endpoints

#### 5.2 Backup Strategy
1. **Database backups**: Daily via Coolify to S3-compatible storage
2. **Media files**: Strapi uploads to cloud storage
3. **Configuration**: Export Coolify settings regularly

#### 5.3 Backup Configuration
```yaml
# Coolify backup settings
backup:
  schedule: "0 2 * * *"  # Daily at 2 AM
  retention: 30           # Keep 30 days
  destination: s3://backup-bucket/placebo-mk
```

## Docker Setup

### Docker Files Created
```
placeboMk/
├── docker-compose.yml           # Production setup with PostgreSQL
├── docker-compose.dev.yml       # Development setup with hot reload
├── backend/
│   ├── Dockerfile              # Production Dockerfile
│   └── Dockerfile.dev          # Development Dockerfile
├── frontend/
│   ├── Dockerfile              # Production Dockerfile (Nginx)
│   ├── Dockerfile.dev          # Development Dockerfile
│   └── nginx.conf              # Nginx configuration
└── cms/cms/
    ├── Dockerfile              # Production Dockerfile
    └── Dockerfile.dev          # Development Dockerfile
```

### Local Development with Docker

#### Prerequisites
- Docker Desktop
- Docker Compose
- Node.js 20+ (optional, for local development without Docker)

#### Quick Start - Development Mode
```bash
# Clone repository
git clone https://github.com/your-org/placeboMk.git
cd placeboMk

# Start development environment with hot reload
docker-compose -f docker-compose.dev.yml up -d

# Access applications:
# Frontend: http://localhost:5173
# Backend API: http://localhost:3000
# Strapi CMS: http://localhost:1337/admin
```

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

# Access applications:
# Frontend: http://localhost:3001
# Backend API: http://localhost:3000
# Strapi CMS: http://localhost:1337
# PostgreSQL: localhost:5432
```

#### Test Docker Setup
```bash
# Run comprehensive test
./scripts/test-docker.sh

# Or manually test
docker-compose build
docker-compose up -d
docker-compose ps
```

### Development Commands
```bash
# Development environment
docker-compose -f docker-compose.dev.yml up -d      # Start dev
docker-compose -f docker-compose.dev.yml down       # Stop dev
docker-compose -f docker-compose.dev.yml logs -f    # View dev logs

# Production environment (local testing)
docker-compose up -d                                # Start prod
docker-compose down                                 # Stop prod
docker-compose logs -f                              # View prod logs
docker-compose build                                # Rebuild images

# Database operations
docker-compose exec postgres psql -U placebo_user -d placebo_db  # PostgreSQL shell
docker-compose exec backend npm run migration:run                # Run migrations

# Service management
docker-compose restart backend    # Restart backend
docker-compose restart frontend   # Restart frontend
docker-compose restart cms        # Restart CMS
```

## Production Checklist

### Pre-Deployment
- [ ] Domain DNS propagated (48 hours)
- [ ] SSL certificates issued
- [ ] Database migrated and tested
- [ ] Environment variables configured
- [ ] Backup system tested
- [ ] Monitoring configured

### Deployment Day
1. **Morning**: Final testing of staging environment
2. **Afternoon**: Deploy to production (low traffic time)
3. **Evening**: Monitor performance and fix issues

### Post-Deployment
- [ ] Verify all services are running
- [ ] Test critical user flows
- [ ] Check SSL certificates
- [ ] Verify backups are working
- [ ] Monitor error rates

## Troubleshooting

### Common Issues

#### 1. Database Connection Failed
```bash
# Check PostgreSQL logs
docker-compose logs postgres

# Test connection
docker-compose exec postgres psql -U placebo -d placebomk
```

#### 2. Build Failures
- Check Node.js version compatibility
- Verify package.json dependencies
- Check build logs in Coolify

#### 3. SSL Certificate Issues
- Verify DNS records
- Check Traefik logs: `docker-compose logs traefik`
- Manually renew: `docker-compose exec traefik traefik cert`

#### 4. CORS Errors
- Verify CORS_ORIGIN environment variable
- Check backend CORS configuration
- Test API calls from frontend

### Debug Commands
```bash
# Check container status
docker-compose ps

# View application logs
docker-compose logs --tail=100 backend

# Shell into container
docker-compose exec backend sh

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

## Performance Optimization

### Frontend
- Enable Vite build optimization
- Configure CDN for static assets
- Implement code splitting
- Optimize images

### Backend
- Implement Redis caching
- Database query optimization
- Enable compression
- Configure connection pooling

### Database
- Add appropriate indexes
- Regular vacuum and analyze
- Connection pool tuning
- Read replicas for high traffic

## Scaling Strategy

### Vertical Scaling (First Step)
- Upgrade VPS: 8GB RAM, 4 vCPU
- Increase PostgreSQL memory
- Add Redis cache

### Horizontal Scaling
- Add application replicas
- Load balancing with Traefik
- Database read replicas
- CDN for static assets

### Cost Optimization
- Right-size VPS resources
- Use object storage for media
- Implement caching to reduce database load
- Monitor and optimize queries

## Maintenance Schedule

### Daily
- Check application logs
- Verify backup completion
- Monitor resource usage
- Review error rates

### Weekly
- Update dependencies (security patches)
- Review access logs
- Test restore from backup
- Clean up old logs

### Monthly
- Security audit
- Performance review
- Cost optimization review
- Update deployment documentation

## Emergency Procedures

### Database Corruption
1. Stop affected services
2. Restore from latest backup
3. Verify data integrity
4. Restart services

### Application Crash
1. Check logs for root cause
2. Rollback to previous version
3. Fix issue in development
4. Deploy fix

### DDoS Attack
1. Enable rate limiting
2. Block malicious IPs
3. Scale up resources temporarily
4. Contact hosting provider

## Support Contacts

### Technical Support
- **Coolify Documentation**: https://coolify.io/docs
- **Docker Support**: https://docs.docker.com
- **PostgreSQL Docs**: https://www.postgresql.org/docs

### Macedonian Hosting Providers
- **Hetzner**: German-based, good for Macedonian audience
- **DigitalOcean**: Amsterdam datacenter
- **Local Providers**: Check for Macedonian hosting companies

## Cost Estimates

| Resource | Monthly Cost | Annual Cost |
|----------|-------------|-------------|
| VPS (4GB/2CPU) | €12 | €144 |
| Domain (placebo.mk) | €15/year | €15 |
| Backup Storage (100GB) | €5 | €60 |
| **Total** | **€17/month** | **€219/year** |

## Success Metrics

### Technical Metrics
- Uptime: >99.9%
- Page load time: <2 seconds
- API response time: <200ms
- Error rate: <0.1%

### Business Metrics
- Monthly visitors
- Article publication rate
- User engagement
- Revenue (if applicable)

## Next Steps

1. **Set up development environment** with Docker
2. **Test migration** from SQLite to PostgreSQL
3. **Deploy to staging** environment
4. **Perform load testing**
5. **Go live** with production deployment

## Changelog

### v1.0.0 - Initial Deployment
- Dockerized application stack
- PostgreSQL migration
- Coolify deployment configuration
- Basic monitoring and backup

### Future Improvements
- Redis caching implementation
- CDN integration
- Advanced monitoring (Prometheus/Grafana)
- Automated testing pipeline
- Macedonian language optimization