# Deployment Guide for Marketing Intelligence Agent System

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

## Table of Contents

- [Prerequisites](#prerequisites)
- [Docker Deployment](#docker-deployment)
- [Kubernetes Deployment](#kubernetes-deployment)
- [CI/CD Pipeline](#cicd-pipeline)
- [Environment Configuration](#environment-configuration)
- [Security Best Practices](#security-best-practices)
- [Monitoring and Maintenance](#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:
```bash
git clone https://github.com/yourcompany/marketing-agent.git
cd marketing-agent
```

2. Copy environment template:
```bash
cp .env.example .env
```

3. Edit `.env` file with your configurations:
```bash
# 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:
```bash
# 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:
```bash
docker-compose exec api-gateway node scripts/init-admin.js
```

### Production Deployment

For production deployment, use the production compose file:

```bash
# 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:
```nginx
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:
```bash
cd helm/marketing-agent
helm dependency update
```

2. Create namespace:
```bash
kubectl create namespace marketing-agent
```

3. Create secrets:
```bash
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:
```bash
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:

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

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

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

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

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

```bash
# Manual backup
./scripts/backup.sh

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

### Maintenance Tasks

1. **Database maintenance**:
```bash
# 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**:
```bash
# Configured in Docker with max-size and max-file
# For K8s, use log shipping solutions
```

3. **Update dependencies**:
```bash
# 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](../api/README.md)
- Configure [Monitoring Dashboards](../monitoring/README.md)
- Set up [Backup Strategy](../backup/README.md)
- Implement [Disaster Recovery Plan](../disaster-recovery/README.md)