Deployment Guide¶
Обзор¶
Comprehensive guide по deployment Saga DeFi Platform на production VPS сервер.
Deployment Architecture¶
Blue-Green Deployment¶
Saga использует Blue-Green deployment стратегию для zero-downtime updates:
- Blue Environment: Текущая production версия (port 8081)
- Green Environment: Новая версия для deployment (port 8082)
- Nginx: Proxy переключается между blue/green
- Automatic Rollback: При ошибках automatic rollback к предыдущей версии
Production Infrastructure¶
VPS Server (188.42.218.164)
├── /opt/saga/
│ ├── blue/ # Blue environment (port 8081)
│ ├── green/ # Green environment (port 8082)
│ ├── shared/ # Shared resources
│ │ ├── logs/
│ │ └── deployment-state.json
│ └── code/ # Deployment scripts
├── Nginx (port 8080) # Public proxy
├── PostgreSQL (5432) # Database
└── Anvil (8545) # Blockchain node
Deployment Commands¶
Quick Deployment¶
# Полный Blue-Green deployment
make deploy
# Проверка статуса deployment
make deploy-status
# Rollback к предыдущей версии
make deploy-rollback
Advanced Commands¶
# Альтернативный вызов через modular Makefile
make -f makefiles/deployment.mk deploy
make -f makefiles/deployment.mk deploy-status
make -f makefiles/deployment.mk deploy-rollback
# Прямой SSH доступ
ssh cloud-user@188.42.218.164
Pre-Deployment Checklist¶
1. Code Quality¶
# Run all tests
make test-all
# Run linters
make lint
# Check for TODO/FIXME
grep -r "TODO\|FIXME" backend/ frontend/
# Verify no console.log in production code
grep -r "console.log" frontend/ --exclude-dir=node_modules
2. Version Management¶
# Update version with meaningful commit message
make commit MESSAGE="feat: new feature description"
# Or version bump
make commit-minor MESSAGE="feat: new feature"
make commit-major MESSAGE="feat!: breaking changes"
# Verify VERSION file updated
cat VERSION
3. Documentation¶
# Ensure README updated
vim README.md
# Check documentation links
make analyze
# Update CHANGELOG if exists
vim CHANGELOG.md
4. Environment Variables¶
# Verify .env on VPS has required variables
ssh cloud-user@188.42.218.164 'cat /opt/saga/shared/.env'
# Required variables:
# - DB_PASSWORD
# - JWT_SECRET
# - HD_WALLET_MASTER_ADDRESS
# - BLOCKCHAIN_RPC_URL
Deployment Process¶
Automatic Deployment (Recommended)¶
# 1. Commit and push changes
make commit MESSAGE="feat: describe your changes"
git push origin master
# 2. Run deployment command
make deploy
# 3. Monitor deployment
# Watch logs for errors
# Script automatically:
# - Determines active environment (blue/green)
# - Deploys to inactive environment
# - Runs health checks
# - Switches Nginx proxy
# - Verifies new version working
# - Rolls back on failure
Manual Deployment (Advanced)¶
# 1. SSH to VPS
ssh cloud-user@188.42.218.164
# 2. Navigate to saga directory
cd /opt/saga/code
# 3. Pull latest changes
git pull origin master
# 4. Run deployment script
bash deployments/vps/deploy.sh
# 5. Monitor logs
tail -f /opt/saga/shared/logs/deployment.log
🏥 Health Checks¶
Automatic Health Checks¶
Deployment script автоматически проверяет:
# 1. HTTP Health endpoint
curl -f http://localhost:8081/health
# 2. Database connectivity
psql -U aisee -h localhost -d saga -c "SELECT 1"
# 3. Blockchain connectivity
curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
http://188.42.218.164:8545
# 4. Docker container status
docker ps | grep saga-blue
Manual Health Checks¶
# Check system health
make deploy-status
# Or via SSH
ssh cloud-user@188.42.218.164 'systemctl status saga-blue saga-green'
# Check Nginx status
ssh cloud-user@188.42.218.164 'systemctl status nginx'
# Check PostgreSQL
ssh cloud-user@188.42.218.164 'systemctl status postgresql'
Troubleshooting Deployment¶
Deployment Fails¶
# 1. Check deployment logs
ssh cloud-user@188.42.218.164 'tail -100 /opt/saga/shared/logs/deployment.log'
# 2. Check container logs
ssh cloud-user@188.42.218.164 'docker logs saga-green --tail=50'
# 3. Rollback to previous version
make deploy-rollback
# 4. Investigate issue locally
make restart
make test-all
Container Won't Start¶
# Check Docker status
ssh cloud-user@188.42.218.164 'docker ps -a'
# Check for port conflicts
ssh cloud-user@188.42.218.164 'lsof -i :8081 -i :8082'
# Check disk space
ssh cloud-user@188.42.218.164 'df -h'
# Check memory usage
ssh cloud-user@188.42.218.164 'free -h'
Database Migration Issues¶
# Check migration status
ssh cloud-user@188.42.218.164 'docker exec saga-green /app/bin/migrate version'
# Manually run migrations
ssh cloud-user@188.42.218.164 'docker exec saga-green /app/bin/migrate up'
# Rollback migration
ssh cloud-user@188.42.218.164 'docker exec saga-green /app/bin/migrate down'
Nginx Issues¶
# Check Nginx configuration
ssh cloud-user@188.42.218.164 'nginx -t'
# Reload Nginx
ssh cloud-user@188.42.218.164 'systemctl reload nginx'
# Check Nginx logs
ssh cloud-user@188.42.218.164 'tail -50 /var/log/nginx/error.log'
Security Considerations¶
SSL/TLS Certificates¶
# Check certificate status
ssh cloud-user@188.42.218.164 'certbot certificates'
# Renew certificates
ssh cloud-user@188.42.218.164 'certbot renew'
# Verify HTTPS working
curl -I https://saga.surf
curl -I https://app.saga.surf
curl -I https://admin.saga.surf
Firewall Rules¶
# Check firewall status
ssh cloud-user@188.42.218.164 'ufw status'
# Allowed ports:
# - 22 (SSH)
# - 80 (HTTP)
# - 443 (HTTPS)
# - 8080 (Internal Nginx proxy)
# - 8545 (Blockchain RPC)
# - 5432 (PostgreSQL - localhost only)
Environment Variables¶
# NEVER commit .env to git
# ALWAYS use environment variables for secrets
# ALWAYS rotate JWT_SECRET periodically
# Check .env security
ssh cloud-user@188.42.218.164 'ls -la /opt/saga/shared/.env'
# Should show: -rw------- (600 permissions)
Monitoring¶
System Metrics¶
# CPU and Memory usage
ssh cloud-user@188.42.218.164 'top -bn1 | head -20'
# Disk usage
ssh cloud-user@188.42.218.164 'df -h'
# Docker stats
ssh cloud-user@188.42.218.164 'docker stats --no-stream'
Application Logs¶
# View live logs
ssh cloud-user@188.42.218.164 'docker logs saga-blue --follow'
# Search for errors
ssh cloud-user@188.42.218.164 'docker logs saga-blue | grep ERROR'
# Export logs
ssh cloud-user@188.42.218.164 'docker logs saga-blue > saga-logs.txt'
Database Monitoring¶
# Active connections
ssh cloud-user@188.42.218.164 'psql -U aisee -d saga -c "SELECT count(*) FROM pg_stat_activity"'
# Database size
ssh cloud-user@188.42.218.164 'psql -U aisee -d saga -c "SELECT pg_size_pretty(pg_database_size(\"saga\"))"'
# Slow queries
ssh cloud-user@188.42.218.164 'psql -U aisee -d saga -c "SELECT query, calls, total_time FROM pg_stat_statements ORDER BY total_time DESC LIMIT 10"'
Rollback Procedures¶
Automatic Rollback¶
# Deployment script automatically rolls back if:
# - Health checks fail
# - Container won't start
# - Database migration fails
# - Nginx proxy switch fails
# Manual rollback command
make deploy-rollback
Manual Rollback¶
# 1. SSH to VPS
ssh cloud-user@188.42.218.164
# 2. Run rollback script
cd /opt/saga/code
bash deployments/vps/rollback.sh
# 3. Verify rollback successful
systemctl status saga-blue saga-green
curl http://localhost:8080/health
Post-Deployment¶
Verification Steps¶
# 1. Check all services running
make deploy-status
# 2. Verify public URLs
curl -I https://saga.surf
curl -I https://app.saga.surf
curl -I https://admin.saga.surf
# 3. Run smoke tests against production
# (Optional - if you have production smoke tests)
# 4. Check logs for errors
ssh cloud-user@188.42.218.164 'docker logs saga-blue | grep ERROR'
# 5. Monitor metrics for 15-30 minutes
# Watch for increased error rates, memory leaks, etc.
Notification¶
# Notify team about successful deployment
# (Email notifications)
# Document deployment in CHANGELOG
vim CHANGELOG.md
# Tag release in git
git tag -a v2.1.525 -m "Release v2.1.525"
git push origin v2.1.525
Related Documentation¶
📖 Best Practices¶
- ✅ Always run tests before deployment
- ✅ Deploy during low-traffic hours
- ✅ Monitor logs after deployment
- ✅ Keep rollback plan ready
- ✅ Document changes in CHANGELOG
- ✅ Notify team before/after deployment
- ✅ Test rollback procedure periodically
- ✅ Maintain backup of database
📋 Метаданные¶
Версия: 2.4.82
Обновлено: 2025-10-21
Статус: Published