# 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](#prerequisites)
2. [Environment Setup](#environment-setup)
3. [Local Development](#local-development)
4. [Docker Deployment](#docker-deployment)
5. [Kubernetes Deployment](#kubernetes-deployment)
6. [Production Deployment](#production-deployment)
7. [Monitoring & Maintenance](#monitoring--maintenance)
8. [Troubleshooting](#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

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

### 2. Create Environment File

```bash
cp .env.example .env
```

Edit `.env` and add your API keys and configuration:

```env
# 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

```bash
# Generate JWT Secret
openssl rand -base64 32

# Generate Encryption Key
openssl rand -hex 32
```

## Local Development

### 1. Install Dependencies

```bash
# 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

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

### 3. Run Database Migrations

```bash
# 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

```bash
# 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

```bash
# Build all Docker images
docker-compose build
```

### 2. Start All Services

```bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Check service health
docker-compose ps
```

### 3. Initialize Data

```bash
# 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

```bash
kubectl create namespace marketing-agent
```

### 2. Create Secrets

```bash
# 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

```bash
# 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

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

## Production Deployment

### 1. Security Hardening

#### SSL/TLS Configuration

```nginx
# 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

```bash
# 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

```sql
-- 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

```javascript
// 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

```bash
# 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

```yaml
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

```bash
#!/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

```bash
# 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

```yaml
# 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

```bash
# 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

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

## Troubleshooting

### Common Issues

#### 1. Service Connection Errors

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

# Restart services
docker-compose restart api-gateway
```

#### 2. Database Connection Issues

```bash
# 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

```bash
# 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

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

### Debug Mode

```bash
# 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