telegram-management-system/marketing-agent/DEPLOYMENT.md

Telegram Marketing Agent System - Deployment Guide

This guide provides comprehensive instructions for deploying the Telegram Marketing Agent System in various environments.

Table of Contents

1. Prerequisites
2. Environment Setup
3. Local Development
4. Docker Deployment
5. Kubernetes Deployment
6. Production Deployment
7. Monitoring & Maintenance
8. Troubleshooting

Prerequisites

System Requirements

• OS: Linux (Ubuntu 20.04+ recommended), macOS, or Windows with WSL2
• CPU: 4+ cores recommended
• RAM: 16GB minimum, 32GB recommended
• Storage: 50GB+ free space
• Network: Stable internet connection with open ports

Software Requirements

• Docker 20.10+ and Docker Compose 2.0+
• Node.js 18+ and npm 8+
• Git
• MongoDB 5.0+
• PostgreSQL 14+
• Redis 7.0+
• RabbitMQ 3.9+
• Elasticsearch 8.0+ (optional)
• ClickHouse (optional)

API Keys Required

1. Anthropic API Key - For Claude AI integration
2. OpenAI API Key - For content moderation
3. Google Cloud Project - For additional NLP services
4. Telegram API Credentials - API ID and Hash

Environment Setup

1. Clone the Repository

git clone https://github.com/your-org/telegram-marketing-agent.git
cd telegram-marketing-agent/marketing-agent

2. Create Environment File

cp .env.example .env

Edit .env and add your API keys and configuration:

# Required API Keys
ANTHROPIC_API_KEY=your_anthropic_api_key
OPENAI_API_KEY=your_openai_api_key
GOOGLE_CLOUD_PROJECT=your_project_id

# JWT Secret (generate a secure random string)
JWT_SECRET=your-super-secret-key-min-32-chars

# Telegram Configuration
TELEGRAM_API_ID=your_telegram_api_id
TELEGRAM_API_HASH=your_telegram_api_hash

# Update other configurations as needed

3. Generate Secure Keys

# Generate JWT Secret
openssl rand -base64 32

# Generate Encryption Key
openssl rand -hex 32

Local Development

1. Install Dependencies

# Install dependencies for all services
for service in services/*; do
  if [ -d "$service" ]; then
    echo "Installing dependencies for $service"
    cd "$service"
    npm install
    cd ../..
  fi
done

2. Start Infrastructure Services

# Start databases and message brokers
docker-compose up -d postgres mongodb redis rabbitmq elasticsearch

3. Run Database Migrations

# MongoDB indexes
docker exec -it marketing_mongodb mongosh marketing_agent --eval '
db.tasks.createIndex({ taskId: 1 }, { unique: true });
db.campaigns.createIndex({ campaignId: 1 }, { unique: true });
db.sessions.createIndex({ sessionId: 1 }, { unique: true });
db.sessions.createIndex({ updatedAt: 1 }, { expireAfterSeconds: 2592000 });
'

4. Start Services Individually

# Terminal 1: API Gateway
cd services/api-gateway
npm run dev

# Terminal 2: Orchestrator
cd services/orchestrator
npm run dev

# Terminal 3: Claude Agent
cd services/claude-agent
npm run dev

# Continue for other services...

Docker Deployment

1. Build All Services

# Build all Docker images
docker-compose build

2. Start All Services

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Check service health
docker-compose ps

3. Initialize Data

# Create admin user
curl -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "secure_password",
    "email": "admin@example.com"
  }'

4. Access Services

• API Gateway: http://localhost:3000
• API Documentation: http://localhost:3000/api-docs
• RabbitMQ Management: http://localhost:15672 (admin/admin)
• Grafana: http://localhost:3001 (admin/admin)
• Prometheus: http://localhost:9090

Kubernetes Deployment

1. Create Namespace

kubectl create namespace marketing-agent

2. Create Secrets

# Create secret for API keys
kubectl create secret generic api-keys \
  --from-literal=anthropic-api-key=$ANTHROPIC_API_KEY \
  --from-literal=openai-api-key=$OPENAI_API_KEY \
  --from-literal=jwt-secret=$JWT_SECRET \
  -n marketing-agent

3. Apply Configurations

# Apply all Kubernetes manifests
kubectl apply -f infrastructure/kubernetes/ -n marketing-agent

# Check deployment status
kubectl get pods -n marketing-agent
kubectl get services -n marketing-agent

4. Setup Ingress

# Apply ingress configuration
kubectl apply -f infrastructure/kubernetes/ingress.yaml -n marketing-agent

Production Deployment

1. Security Hardening

SSL/TLS Configuration

# nginx/conf.d/ssl.conf
server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://api-gateway:3000;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Environment Variables

# Production .env
NODE_ENV=production
LOG_LEVEL=warn
DEBUG=false

# Use strong passwords
POSTGRES_PASSWORD=$(openssl rand -base64 32)
RABBITMQ_DEFAULT_PASS=$(openssl rand -base64 32)

2. Database Setup

PostgreSQL

-- Create production database
CREATE DATABASE marketing_agent_prod;
CREATE USER marketing_prod WITH ENCRYPTED PASSWORD 'strong_password';
GRANT ALL PRIVILEGES ON DATABASE marketing_agent_prod TO marketing_prod;

-- Enable extensions
\c marketing_agent_prod
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pgcrypto";

MongoDB

// Create production user
use marketing_agent_prod
db.createUser({
  user: "marketing_prod",
  pwd: "strong_password",
  roles: [
    { role: "readWrite", db: "marketing_agent_prod" }
  ]
})

3. Scaling Configuration

Docker Swarm

# Initialize swarm
docker swarm init

# Deploy stack
docker stack deploy -c docker-compose.prod.yml marketing-agent

# Scale services
docker service scale marketing-agent_api-gateway=3
docker service scale marketing-agent_orchestrator=2

Kubernetes HPA

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-gateway-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-gateway
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

4. Backup Strategy

#!/bin/bash
# backup.sh

# Backup MongoDB
docker exec marketing_mongodb mongodump \
  --uri="mongodb://localhost:27017/marketing_agent" \
  --out=/backup/mongodb-$(date +%Y%m%d)

# Backup PostgreSQL
docker exec marketing_postgres pg_dump \
  -U marketing_user marketing_agent \
  > /backup/postgres-$(date +%Y%m%d).sql

# Backup Redis
docker exec marketing_redis redis-cli BGSAVE

# Upload to S3
aws s3 sync /backup s3://your-backup-bucket/$(date +%Y%m%d)/

Monitoring & Maintenance

1. Health Checks

# Check all services health
curl http://localhost:3000/health/services

# Individual service health
curl http://localhost:3001/health  # Orchestrator
curl http://localhost:3002/health  # Claude Agent

2. Prometheus Alerts

# prometheus/alerts.yml
groups:
  - name: marketing-agent
    rules:
      - alert: ServiceDown
        expr: up{job="api-gateway"} == 0
        for: 5m
        annotations:
          summary: "API Gateway is down"
          
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
        for: 5m
        annotations:
          summary: "High error rate detected"

3. Log Management

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

# Export logs
docker logs marketing_api_gateway > api-gateway.log

# Log rotation
cat > /etc/logrotate.d/marketing-agent << EOF
/var/log/marketing-agent/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
}
EOF

4. Performance Tuning

// Redis optimization
// redis.conf
maxmemory 2gb
maxmemory-policy allkeys-lru
save 900 1
save 300 10

Troubleshooting

Common Issues

1. Service Connection Errors

# Check network connectivity
docker network ls
docker network inspect marketing-agent_marketing_network

# Restart services
docker-compose restart api-gateway

2. Database Connection Issues

# Test MongoDB connection
docker exec -it marketing_mongodb mongosh --eval "db.adminCommand('ping')"

# Test PostgreSQL connection
docker exec -it marketing_postgres psql -U marketing_user -d marketing_agent -c "SELECT 1"

3. Memory Issues

# Check memory usage
docker stats

# Increase memory limits in docker-compose.yml
services:
  claude-agent:
    mem_limit: 2g
    memswap_limit: 2g

4. API Rate Limiting

// Adjust rate limits in config
rateLimiting: {
  windowMs: 15 * 60 * 1000,
  max: 200  // Increase limit
}

Debug Mode

# Enable debug logging
export DEBUG=true
export LOG_LEVEL=debug

# Run with verbose output
docker-compose up

Support

For additional support:

• Check logs in /logs directory
• Review error messages in Grafana dashboards
• Contact support team with service logs and error details

Security Checklist

• Change all default passwords
• Enable SSL/TLS for all external endpoints
• Configure firewall rules
• Enable audit logging
• Set up backup automation
• Configure monitoring alerts
• Review and update dependencies regularly
• Implement rate limiting
• Enable CORS properly
• Rotate API keys periodically