telegram-management-system/marketing-agent/docs/deployment/README.md

Deployment Guide for Marketing Intelligence Agent System

This guide covers various deployment options for the Marketing Intelligence Agent System.

Table of Contents

• Prerequisites
• Docker Deployment
• Kubernetes Deployment
• CI/CD Pipeline
• Environment Configuration
• Security Best Practices
• Monitoring and Maintenance

Prerequisites

System Requirements

• CPU: Minimum 8 cores (16 cores recommended for production)
• Memory: Minimum 16GB RAM (32GB recommended for production)
• Storage: Minimum 100GB SSD storage
• Network: Stable internet connection with low latency

Software Requirements

• Docker 20.10+ and Docker Compose 2.0+
• Kubernetes 1.24+ (for K8s deployment)
• Helm 3.10+ (for K8s deployment)
• Git
• Node.js 18+ (for local development)

External Services

• Telegram account with API credentials
• Anthropic API key (for Claude AI)
• OpenAI API key (optional, for safety checks)
• SMTP server or email service (for notifications)
• S3-compatible storage (for backups)

Docker Deployment

Quick Start

1. Clone the repository:

git clone https://github.com/yourcompany/marketing-agent.git
cd marketing-agent

2. Copy environment template:

cp .env.example .env

3. Edit .env file with your configurations:

# Required configurations
ANTHROPIC_API_KEY=your_anthropic_api_key
JWT_SECRET=your_jwt_secret
MONGO_ROOT_PASSWORD=secure_password
REDIS_PASSWORD=secure_password
# ... other configurations

4. Build and start services:

# Build all images
./scripts/docker-build.sh

# Start services
docker-compose up -d

# Wait for services to be ready
./scripts/wait-for-services.sh

5. Initialize admin user:

docker-compose exec api-gateway node scripts/init-admin.js

Production Deployment

For production deployment, use the production compose file:

# Build with production optimizations
./scripts/docker-build.sh --tag v1.0.0 --registry ghcr.io/yourcompany

# Deploy with production settings
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

SSL/TLS Configuration

1. Place SSL certificates in infrastructure/ssl/:

infrastructure/ssl/
├── cert.pem
├── key.pem
└── dhparam.pem

2. Update nginx configuration:

server {
    listen 443 ssl http2;
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    # ... other SSL settings
}

Kubernetes Deployment

Using Helm

1. Add Helm dependencies:

cd helm/marketing-agent
helm dependency update

2. Create namespace:

kubectl create namespace marketing-agent

3. Create secrets:

kubectl create secret generic marketing-agent-secrets \
  --from-literal=anthropic-api-key=$ANTHROPIC_API_KEY \
  --from-literal=jwt-secret=$JWT_SECRET \
  -n marketing-agent

4. Install the chart:

helm install marketing-agent ./helm/marketing-agent \
  --namespace marketing-agent \
  --values ./helm/marketing-agent/values.yaml \
  --values ./helm/marketing-agent/values.prod.yaml

Manual Kubernetes Deployment

If not using Helm, apply the manifests directly:

kubectl apply -f infrastructure/k8s/namespace.yaml
kubectl apply -f infrastructure/k8s/configmap.yaml
kubectl apply -f infrastructure/k8s/secrets.yaml
kubectl apply -f infrastructure/k8s/deployments/
kubectl apply -f infrastructure/k8s/services/
kubectl apply -f infrastructure/k8s/ingress.yaml

Scaling

Horizontal Pod Autoscaling is configured for key services:

# Check HPA status
kubectl get hpa -n marketing-agent

# Manual scaling
kubectl scale deployment marketing-agent-api-gateway --replicas=5 -n marketing-agent

CI/CD Pipeline

GitHub Actions

The project includes comprehensive CI/CD pipelines:

Continuous Integration (.github/workflows/ci.yml)

• Code linting and formatting
• Security scanning
• Unit and integration tests
• Docker image building
• E2E testing
• Performance testing

Continuous Deployment (.github/workflows/cd.yml)

• Automatic deployment to staging on main branch
• Production deployment on version tags
• Database migrations
• Blue-green deployment
• Automated rollback on failure

Security Scanning (.github/workflows/security.yml)

• Container vulnerability scanning
• SAST (Static Application Security Testing)
• Secret scanning
• Dependency auditing
• Infrastructure security checks

Setting up CI/CD

1. Configure GitHub secrets:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
ANTHROPIC_API_KEY
SLACK_WEBHOOK
DOCKER_REGISTRY_USERNAME
DOCKER_REGISTRY_PASSWORD

2. Configure deployment environments in GitHub:

• staging
• production

3. Enable branch protection rules for main branch

Environment Configuration

Environment Variables

Create environment-specific files:

• .env.development
• .env.staging
• .env.production

Key configurations:

# Application
NODE_ENV=production
LOG_LEVEL=info

# Security
JWT_SECRET=<generate-with-openssl-rand>
ENCRYPTION_KEY=<32-byte-key>

# Database
MONGODB_URI=mongodb://user:pass@mongodb:27017/marketing_agent
REDIS_PASSWORD=<secure-password>

# External Services
ANTHROPIC_API_KEY=<your-key>
TELEGRAM_SYSTEM_URL=<your-telegram-system-url>

# Monitoring
GRAFANA_ADMIN_PASSWORD=<secure-password>
ELASTIC_PASSWORD=<secure-password>

Configuration Management

Use ConfigMaps for non-sensitive configurations:

apiVersion: v1
kind: ConfigMap
metadata:
  name: marketing-agent-config
data:
  NODE_ENV: "production"
  LOG_LEVEL: "info"
  RATE_LIMIT_WINDOW: "60000"
  RATE_LIMIT_MAX: "100"

Security Best Practices

1. Secret Management

• Use Kubernetes secrets or external secret managers (Vault, AWS Secrets Manager)
• Rotate secrets regularly
• Never commit secrets to version control

2. Network Security

• Enable network policies to restrict traffic
• Use TLS for all communications
• Implement proper CORS policies

3. Container Security

• Run containers as non-root user
• Use minimal base images (Alpine)
• Scan images for vulnerabilities
• Keep dependencies updated

4. Access Control

• Implement RBAC in Kubernetes
• Use service accounts with minimal permissions
• Enable audit logging

5. Data Protection

• Encrypt data at rest
• Use TLS for data in transit
• Implement proper backup encryption
• Follow GDPR compliance guidelines

Monitoring and Maintenance

Health Checks

All services expose health endpoints:

• /health - Basic health check
• /health/live - Liveness probe
• /health/ready - Readiness probe

Metrics and Monitoring

1. Access Grafana dashboards:

http://localhost:3032 (Docker)
https://grafana.your-domain.com (K8s)

2. Key metrics to monitor:

• API response times
• Error rates
• Message delivery success rate
• System resource usage
• Database performance

Logging

Centralized logging with Elasticsearch:

# View logs
docker-compose logs -f api-gateway

# Search logs in Elasticsearch
curl -X GET "localhost:9200/logs-*/_search?q=error"

Backup and Recovery

Automated backups are configured to run daily:

# Manual backup
./scripts/backup.sh

# Restore from backup
./scripts/restore.sh backup-20240115-020000.tar.gz

Maintenance Tasks

1. Database maintenance:

# MongoDB optimization
docker-compose exec mongodb mongosh --eval "db.adminCommand({compact: 'campaigns'})"

# Redis memory optimization
docker-compose exec redis redis-cli --raw MEMORY DOCTOR

2. Log rotation:

# Configured in Docker with max-size and max-file
# For K8s, use log shipping solutions

3. Update dependencies:

# Check for updates
npm audit

# Update dependencies
npm update

Troubleshooting

Common issues and solutions:

1. Service not starting:

   • Check logs: docker-compose logs <service>
   • Verify environment variables
   • Check resource availability

2. Database connection issues:

   • Verify connection strings
   • Check network connectivity
   • Ensure database is initialized

3. Performance issues:

   • Check resource usage
   • Review slow query logs
   • Enable performance profiling

4. Deployment failures:

   • Check CI/CD logs
   • Verify credentials and permissions
   • Review deployment prerequisites

Next Steps

• Review API Documentation
• Configure Monitoring Dashboards
• Set up Backup Strategy
• Implement Disaster Recovery Plan