TypeDialog/docs/deployment.md

TypeDialog Agents - Deployment Guide

Production deployment guide for TypeDialog Agents system.

Table of Contents

1. Deployment Options
2. Local Development
3. Systemd Service
4. Docker Deployment
5. Kubernetes
6. Reverse Proxy
7. Monitoring
8. Security
9. Performance Tuning
10. Backup & Recovery

---

Deployment Options

Method	Complexity	Scalability	Best For
Systemd Service	Low	Single server	Small deployments
Docker	Medium	Multi-container	Standard deployments
Kubernetes	High	Cluster	Large-scale production
Serverless	Medium	Auto-scale	Variable workloads

---

Local Development

Development Server

# Start development server with hot reload
cargo watch -x 'run --package typedialog-ag -- serve --port 8765'

# Or use release build
cargo run --release --package typedialog-ag -- serve --port 8765

Environment Setup

Create .env file:

# .env
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-openai-key
RUST_LOG=info
TYPEAGENT_CACHE_DIR=/tmp/typeagent-cache

Load environment:

source .env
typedialog-ag serve --port 8765

---

Systemd Service (Linux)

Create Service File

Create /etc/systemd/system/typeagent.service:

[Unit]
Description=TypeDialog Agent HTTP Server
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=typeagent
Group=typeagent
WorkingDirectory=/opt/typeagent
ExecStart=/usr/local/bin/typedialog-ag serve --port 8765

# Environment
Environment="ANTHROPIC_API_KEY=sk-ant-your-key-here"
Environment="RUST_LOG=info"
Environment="TYPEAGENT_CACHE_DIR=/var/cache/typeagent"

# Restart policy
Restart=always
RestartSec=10
StartLimitBurst=5
StartLimitIntervalSec=60

# Resource limits
MemoryLimit=2G
CPUQuota=200%

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/cache/typeagent /var/log/typeagent

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=typeagent

[Install]
WantedBy=multi-user.target

Setup Service

# Create user
sudo useradd -r -s /bin/false typeagent

# Create directories
sudo mkdir -p /opt/typeagent/agents
sudo mkdir -p /var/cache/typeagent
sudo mkdir -p /var/log/typeagent

# Copy binary
sudo cp target/release/typedialog-ag /usr/local/bin/
sudo chmod 755 /usr/local/bin/typedialog-ag

# Copy agents
sudo cp -r agents/* /opt/typeagent/agents/

# Set permissions
sudo chown -R typeagent:typeagent /opt/typeagent
sudo chown -R typeagent:typeagent /var/cache/typeagent
sudo chown -R typeagent:typeagent /var/log/typeagent

# Install service
sudo systemctl daemon-reload
sudo systemctl enable typeagent
sudo systemctl start typeagent

Manage Service

# Start service
sudo systemctl start typeagent

# Stop service
sudo systemctl stop typeagent

# Restart service
sudo systemctl restart typeagent

# Check status
sudo systemctl status typeagent

# View logs
sudo journalctl -u typeagent -f

# View last 100 lines
sudo journalctl -u typeagent -n 100

Update Deployment

# Build new version
cargo build --release --package typedialog-ag

# Stop service
sudo systemctl stop typeagent

# Update binary
sudo cp target/release/typedialog-ag /usr/local/bin/

# Start service
sudo systemctl start typeagent

# Verify
sudo systemctl status typeagent

---

Docker Deployment

Dockerfile

Create docker/Dockerfile:

# Multi-stage build for minimal image size
FROM rust:1.75-slim-bullseye AS builder

# Install dependencies
RUN apt-get update && apt-get install -y \
    pkg-config \
    libssl-dev \
    && rm -rf /var/lib/apt/lists/*

# Create app directory
WORKDIR /app

# Copy manifests
COPY Cargo.toml Cargo.lock ./
COPY crates ./crates

# Build release binary
RUN cargo build --release --package typedialog-ag

# Runtime stage
FROM debian:bullseye-slim

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \
    libssl1.1 \
    && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN useradd -r -s /bin/false typeagent

# Create directories
RUN mkdir -p /app/agents /var/cache/typeagent
RUN chown -R typeagent:typeagent /app /var/cache/typeagent

# Copy binary from builder
COPY --from=builder /app/target/release/typedialog-ag /usr/local/bin/

# Copy agents
COPY agents /app/agents

# Switch to non-root user
USER typeagent
WORKDIR /app

# Expose port
EXPOSE 8765

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8765/health || exit 1

# Run server
CMD ["typedialog-ag", "serve", "--port", "8765"]

Build Image

cd /path/to/typedialog

# Build image
docker build -t typeagent:latest -f docker/Dockerfile .

# Build with specific tag
docker build -t typeagent:v1.0.0 -f docker/Dockerfile .

# Verify image
docker images | grep typeagent

Run Container

# Run with environment variables
docker run -d \
  --name typeagent \
  -p 8765:8765 \
  -e ANTHROPIC_API_KEY=sk-ant-your-key-here \
  -e RUST_LOG=info \
  --restart unless-stopped \
  typeagent:latest

# Run with volume mounts
docker run -d \
  --name typeagent \
  -p 8765:8765 \
  -e ANTHROPIC_API_KEY=sk-ant-your-key-here \
  -v $(pwd)/agents:/app/agents:ro \
  -v typeagent-cache:/var/cache/typeagent \
  --restart unless-stopped \
  typeagent:latest

# Check logs
docker logs -f typeagent

# Check health
docker ps | grep typeagent
curl http://localhost:8765/health

Docker Compose

Create docker/docker-compose.yml:

version: '3.8'

services:
  typeagent:
    image: typeagent:latest
    build:
      context: ..
      dockerfile: docker/Dockerfile
    container_name: typeagent
    restart: unless-stopped
    ports:
      - "8765:8765"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      - RUST_LOG=info
      - TYPEAGENT_CACHE_DIR=/var/cache/typeagent
    volumes:
      - ../agents:/app/agents:ro
      - typeagent-cache:/var/cache/typeagent
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8765/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

  # Optional: Nginx reverse proxy
  nginx:
    image: nginx:alpine
    container_name: typeagent-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - typeagent

volumes:
  typeagent-cache:
    driver: local

Usage:

cd docker

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Restart
docker-compose restart

# Update and restart
docker-compose build
docker-compose up -d

---

Kubernetes

Deployment Manifest

Create k8s/deployment.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: typeagent

---
apiVersion: v1
kind: Secret
metadata:
  name: typeagent-secrets
  namespace: typeagent
type: Opaque
stringData:
  anthropic-api-key: sk-ant-your-key-here
  openai-api-key: sk-your-openai-key

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: typeagent-config
  namespace: typeagent
data:
  RUST_LOG: "info"
  TYPEAGENT_CACHE_DIR: "/var/cache/typeagent"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: typeagent
  namespace: typeagent
  labels:
    app: typeagent
spec:
  replicas: 3
  selector:
    matchLabels:
      app: typeagent
  template:
    metadata:
      labels:
        app: typeagent
    spec:
      containers:
      - name: typeagent
        image: typeagent:latest
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8765
          name: http
        env:
        - name: ANTHROPIC_API_KEY
          valueFrom:
            secretKeyRef:
              name: typeagent-secrets
              key: anthropic-api-key
        - name: RUST_LOG
          valueFrom:
            configMapKeyRef:
              name: typeagent-config
              key: RUST_LOG
        - name: TYPEAGENT_CACHE_DIR
          valueFrom:
            configMapKeyRef:
              name: typeagent-config
              key: TYPEAGENT_CACHE_DIR
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "2000m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8765
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 8765
          initialDelaySeconds: 5
          periodSeconds: 10
        volumeMounts:
        - name: cache
          mountPath: /var/cache/typeagent
      volumes:
      - name: cache
        emptyDir: {}

---
apiVersion: v1
kind: Service
metadata:
  name: typeagent
  namespace: typeagent
spec:
  selector:
    app: typeagent
  ports:
  - port: 80
    targetPort: 8765
    protocol: TCP
  type: ClusterIP

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: typeagent
  namespace: typeagent
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - typeagent.yourdomain.com
    secretName: typeagent-tls
  rules:
  - host: typeagent.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: typeagent
            port:
              number: 80

Deploy:

# Apply manifests
kubectl apply -f k8s/deployment.yaml

# Check status
kubectl get all -n typeagent

# View logs
kubectl logs -n typeagent -l app=typeagent -f

# Scale replicas
kubectl scale deployment/typeagent -n typeagent --replicas=5

# Rolling update
kubectl set image deployment/typeagent typeagent=typeagent:v1.1.0 -n typeagent

---

Reverse Proxy (Nginx)

Nginx Configuration

Create /etc/nginx/sites-available/typeagent:

upstream typeagent {
    # Multiple backend servers for load balancing
    server 127.0.0.1:8765 max_fails=3 fail_timeout=30s;
    # server 127.0.0.1:8766 max_fails=3 fail_timeout=30s;
    # server 127.0.0.1:8767 max_fails=3 fail_timeout=30s;

    keepalive 32;
}

# Rate limiting
limit_req_zone $binary_remote_addr zone=typeagent_limit:10m rate=10r/s;

server {
    listen 80;
    server_name typeagent.yourdomain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name typeagent.yourdomain.com;

    # SSL Configuration
    ssl_certificate /etc/letsencrypt/live/typeagent.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/typeagent.yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;

    # Logging
    access_log /var/log/nginx/typeagent-access.log combined;
    error_log /var/log/nginx/typeagent-error.log warn;

    # Client limits
    client_max_body_size 10M;
    client_body_timeout 60s;

    location / {
        # Rate limiting
        limit_req zone=typeagent_limit burst=20 nodelay;

        # Proxy settings
        proxy_pass http://typeagent;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        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;
        proxy_set_header Connection "";

        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        # Buffering
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }

    # Health check endpoint (no rate limiting)
    location /health {
        proxy_pass http://typeagent;
        access_log off;
    }
}

Enable and test:

# Test configuration
sudo nginx -t

# Enable site
sudo ln -s /etc/nginx/sites-available/typeagent /etc/nginx/sites-enabled/

# Reload nginx
sudo systemctl reload nginx

# Check status
sudo systemctl status nginx

---

Monitoring

Prometheus Metrics

Add metrics endpoint (future enhancement):

// In main.rs
Router::new()
    .route("/metrics", get(metrics_handler))

Logging

Structured logging with tracing:

# Set log level
export RUST_LOG=debug

# JSON format
export RUST_LOG_FORMAT=json

# Specific module
export RUST_LOG=typedialog_ag_core=debug,typedialog_ag=info

Health Checks

# Simple health check
curl http://localhost:8765/health

# Detailed health check script
cat > health-check.sh << 'EOF'
#!/bin/bash
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8765/health)
if [ "$RESPONSE" = "200" ]; then
    echo "OK"
    exit 0
else
    echo "FAIL: HTTP $RESPONSE"
    exit 1
fi
EOF

chmod +x health-check.sh

---

Security

API Key Management

DO NOT:

• Commit API keys to Git
• Hardcode keys in configuration files
• Share keys in plain text

DO:

• Use environment variables
• Use secrets management (Vault, AWS Secrets Manager)
• Rotate keys regularly
• Use separate keys per environment

Network Security

# Firewall rules (UFW)
sudo ufw allow 8765/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# Or iptables
sudo iptables -A INPUT -p tcp --dport 8765 -j ACCEPT

HTTPS/TLS

Use Let's Encrypt for free SSL certificates:

# Install certbot
sudo apt-get install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d typeagent.yourdomain.com

# Auto-renewal
sudo certbot renew --dry-run

---

Performance Tuning

System Limits

Edit /etc/security/limits.conf:

typeagent soft nofile 65536
typeagent hard nofile 65536
typeagent soft nproc 4096
typeagent hard nproc 4096

Cache Tuning

# ~/.typeagent/config.yaml
cache:
  strategy: Both
  max_entries: 5000  # Increase for high traffic
  cache_dir: /var/cache/typeagent

Rust Performance

Build with optimizations:

# Cargo.toml
[profile.release]
lto = true
codegen-units = 1
opt-level = 3

---

Backup & Recovery

Backup Strategy

#!/bin/bash
# backup-typeagent.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/typeagent/$DATE"

mkdir -p "$BACKUP_DIR"

# Backup agents
cp -r /opt/typeagent/agents "$BACKUP_DIR/"

# Backup configuration
cp ~/.typeagent/config.yaml "$BACKUP_DIR/"

# Backup cache (optional)
# tar -czf "$BACKUP_DIR/cache.tar.gz" /var/cache/typeagent

# Compress
tar -czf "/backup/typeagent-$DATE.tar.gz" "$BACKUP_DIR"

# Clean old backups (keep 30 days)
find /backup -name "typeagent-*.tar.gz" -mtime +30 -delete

Recovery

# Extract backup
tar -xzf typeagent-20241223.tar.gz

# Restore agents
sudo cp -r backup/agents/* /opt/typeagent/agents/

# Restore config
cp backup/config.yaml ~/.typeagent/

# Restart service
sudo systemctl restart typeagent

---

Next Steps

1. Choose deployment method
2. Configure monitoring
3. Set up backups
4. Configure SSL/TLS
5. Test failover procedures
6. Document your specific deployment

For issues, see installation.md troubleshooting section.