441 lines
10 KiB
Markdown
441 lines
10 KiB
Markdown
# 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 |