placebo.mk/DEPLOYMENT.md

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

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

# 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

# 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

# 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)

# 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

# Run comprehensive test
./scripts/test-docker.sh

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

Development Commands

# 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

# 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

# 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