Rustelo/info/quick_start_deployment.md

Quick Start Guide - New Deployment Features

Get up and running with Rustelo's new deployment features in minutes!

🚀 What's New

• Docker Containerization - Production-ready containers with hot reload
• GitHub Actions CI/CD - Automated testing, building, and deployment
• Health Check Endpoints - Kubernetes-compatible monitoring
• Prometheus Metrics - Comprehensive application monitoring
• Grafana Dashboards - Beautiful visualizations and alerting
• Feature System - Modular builds for development vs production

⚡ Quick Start (5 minutes)

1. Basic Docker Setup

# Start the application with Docker
docker-compose up -d

# Check if it's running
curl http://localhost:3030/health

# View the application
open http://localhost:3030

2. With Full Monitoring Stack

# Start with monitoring services
docker-compose --profile monitoring up -d

# Wait for services to be ready (takes ~30 seconds)
sleep 30

# Check health status
curl http://localhost:3030/health | jq .

# View metrics
curl http://localhost:3030/metrics

# Open Grafana dashboard
open http://localhost:3000
# Login: admin/admin

3. Production Deployment

# Deploy to production with all features
./deploy.sh deploy -e production --migrate --backup

# Monitor deployment
./deploy.sh status

# Check application health
./deploy.sh health

📊 Monitoring Endpoints

Endpoint	Description	Example
/health	Complete health check	curl http://localhost:3030/health
/health/live	Liveness probe	curl http://localhost:3030/health/live
/health/ready	Readiness probe	curl http://localhost:3030/health/ready
/metrics	Prometheus metrics	curl http://localhost:3030/metrics
/metrics/health	Health metrics (JSON)	curl http://localhost:3030/metrics/health

🔧 Configuration

Enable Metrics and Health Checks

Add to your config.toml:

[app]
enable_metrics = true
enable_health_check = true
enable_compression = true

# Build Features (for Docker builds)
[build]
production_features = ["auth", "content-db", "crypto", "email", "metrics", "tls"]
development_features = ["auth", "content-db", "crypto", "email", "metrics", "examples"]

Environment Variables

# Development
export ENVIRONMENT=development
export RUST_LOG=debug

# Production
export ENVIRONMENT=production
export RUST_LOG=info
export DATABASE_URL=postgresql://user:pass@localhost/db

🐳 Docker Commands

# Development with hot reload (includes examples)
docker-compose --profile dev up -d

# Production build (optimized features)
docker-compose -f docker-compose.yml up -d

# With monitoring
docker-compose --profile monitoring up -d

# Custom feature build
docker build --build-arg CARGO_FEATURES="auth,metrics" --build-arg NO_DEFAULT_FEATURES="true" .

# Scale the application
docker-compose up -d --scale app=3

# View logs
docker-compose logs -f app

# Check container status
docker-compose ps

📈 Grafana Dashboards

After starting with --profile monitoring:

1. Open Grafana: http://localhost:3000
2. Login: admin/admin (change password when prompted)
3. View Dashboards:
   • Rustelo Application Overview
   • System Resources
   • Database Performance
   • Authentication Analytics

🎯 Health Check Examples

Basic Health Check

curl http://localhost:3030/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "0.1.0",
  "uptime_seconds": 3600,
  "components": [
    {
      "name": "database",
      "status": "healthy",
      "response_time_ms": 25
    }
  ]
}

Kubernetes Health Checks

livenessProbe:
  httpGet:
    path: /health/live
    port: 3030
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 3030
  initialDelaySeconds: 5
  periodSeconds: 5

📊 Key Metrics

HTTP Metrics

• rustelo_http_requests_total - Total requests
• rustelo_http_request_duration_seconds - Request duration
• rustelo_http_requests_in_flight - Active requests

Database Metrics

• rustelo_db_connections_active - Active connections
• rustelo_db_connections_idle - Idle connections
• rustelo_db_query_duration_seconds - Query duration

System Metrics

• rustelo_memory_usage_bytes - Memory usage
• rustelo_cpu_usage_percent - CPU usage
• rustelo_uptime_seconds - Application uptime

🔄 CI/CD Setup

GitHub Actions (Automatic)

The CI/CD pipeline automatically:

• ✅ Runs tests on every push
• 🔒 Scans for security vulnerabilities
• 🐳 Builds Docker images
• 🚀 Deploys to staging/production
• 📊 Validates health checks

Manual Setup

1. Fork/Clone the repository
2. Set secrets in GitHub repository settings:
   • DOCKER_USERNAME
   • DOCKER_PASSWORD
   • PRODUCTION_SSH_KEY
3. Push changes to trigger the pipeline

🛠️ Troubleshooting

Application Won't Start

# Check logs
docker-compose logs app

# Check health
curl http://localhost:3030/health

# Restart services
docker-compose restart

Database Connection Issues

# Check database logs
docker-compose logs db

# Test connection
docker-compose exec app psql $DATABASE_URL -c "SELECT 1"

Metrics Not Showing

# Verify metrics endpoint
curl http://localhost:3030/metrics

# Check Prometheus targets
open http://localhost:9090/targets

# Restart monitoring stack
docker-compose restart prometheus grafana

🎛️ Advanced Usage

Custom Metrics

// In your application code
use crate::metrics::MetricsRegistry;

// Record custom events
metrics.record_user_registration();
metrics.record_content_view();
metrics.record_rate_limit_hit();

Custom Health Checks

// Extend health checks
impl MyService {
    pub async fn health_check(&self) -> Result<(), Error> {
        // Custom health validation
        self.check_external_service().await?;
        Ok(())
    }
}

Feature Selection

# Production build (minimal features)
./deploy.sh deploy --features "auth,metrics" --no-default-features

# Development build (all features including examples)
./deploy.sh deploy --default-features

# Custom feature combination
docker build --build-arg CARGO_FEATURES="auth,content-db,metrics" .

Scaling

# Scale horizontally
./deploy.sh scale -s 5

# Scale specific service
docker-compose up -d --scale app=3 --scale worker=2

🎛️ Feature System

Available Features

Feature	Description	Production	Development
auth	Authentication system	✅	✅
content-db	Database content management	✅	✅
crypto	Configuration encryption	✅	✅
email	Email sending system	✅	✅
metrics	Prometheus metrics	✅	✅
tls	HTTPS/TLS support	✅	❌
examples	Example code and demos	❌	✅

Feature Sets

# Production (optimized)
cargo build --features "auth,content-db,crypto,email,metrics,tls" --no-default-features

# Development (full features)
cargo build --features "auth,content-db,crypto,email,metrics,examples"

# Minimal (basic functionality)
cargo build --features "crypto" --no-default-features

🔗 Useful Links

• Prometheus UI: http://localhost:9090
• Grafana Dashboards: http://localhost:3000
• Application Health: http://localhost:3030/health
• Metrics Endpoint: http://localhost:3030/metrics

🆘 Getting Help

1. Check the logs: docker-compose logs -f
2. Health status: curl http://localhost:3030/health
3. Metrics: curl http://localhost:3030/metrics
4. Documentation: See DEPLOYMENT.md for detailed guide

🎉 Next Steps

1. Explore Grafana dashboards for insights
2. Set up alerting for production monitoring
3. Configure CI/CD for your repository
4. Customize metrics for your use case
5. Deploy to production with confidence

---

🚀 Happy Deploying!

Your Rustelo application is now production-ready with enterprise-grade monitoring and deployment capabilities.