461 lines
12 KiB
Markdown
461 lines
12 KiB
Markdown
# 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 |