placebo.mk/DOCKER-README.md

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)

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

# 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

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

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)

NODE_ENV=production
VITE_API_URL=http://localhost:3000
VITE_CMS_URL=http://localhost:1337

CMS (.env)

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

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

# 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

# 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

# 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

curl http://localhost:3000/health

CMS

curl http://localhost:1337/_health

Frontend

curl http://localhost:3001

PostgreSQL

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

# 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

# Check what's using port 3000
sudo lsof -i :3000

# Or use different ports in docker-compose.yml

2. Docker Build Failures

# Clear Docker cache
docker system prune -a

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

3. Database Connection Issues

# 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

# Fix volume permissions
sudo chown -R $USER:$USER .

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

Debug Commands

# 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

# 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

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

monitoring:
  image: prom/prometheus
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml

Backup and Recovery

Database Backup

# 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

# 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

# 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

# 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