QWED Deployment Guide

​

Table of Contents

1. Docker Deployment
2. Kubernetes Deployment
3. Manual / Bare Metal Deployment
4. Environment Variables Reference
5. Production Checklist
6. Troubleshooting
7. Operations & Monitoring

​

Docker Deployment

​

Dockerfile

# Build the image manually
docker build -t qwed-core:5.0.0 .

​

Docker Compose

• qwed-core: The main API server.
• postgres: Primary database.
• redis: Cache and rate limiting.
• jaeger: Distributed tracing.
• prometheus: Metrics collection.
• grafana: Observability dashboards.

# Required — the server will not start without these
DATABASE_URL=postgresql://qwed:your_password@postgres:5432/qwed_db
QWED_CORS_ORIGINS=https://app.yourcompany.com
API_KEY_SECRET=your-generated-secret

# Optional
REDIS_URL=redis://redis:6379/0
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317

# Postgres
POSTGRES_USER=qwed
POSTGRES_PASSWORD=your_password
POSTGRES_DB=qwed_db

# Grafana
GF_SECURITY_ADMIN_USER=admin
GF_SECURITY_ADMIN_PASSWORD=your_grafana_password

python -c "import secrets; print(secrets.token_urlsafe(48))"

docker-compose up -d

• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Grafana: http://localhost:3000
• Jaeger: http://localhost:16686

​

Docker requirement for code execution

​

Kubernetes Deployment

​

Prerequisites

• A running Kubernetes cluster (v1.24+ recommended).
• kubectl configured.
• A PostgreSQL database and Redis instance (managed services recommended for production).

​

Deployment Steps

1. Create Namespace
   kubectl create namespace qwed
   
2. Configure Secrets & ConfigMaps Edit deploy/kubernetes/secret.yaml and replace all __REPLACE_WITH_*__ placeholders with your real values. The DATABASE_URL is now stored in the Secret (not the ConfigMap) because it contains credentials.
   kubectl apply -f deploy/kubernetes/configmap.yaml
   kubectl apply -f deploy/kubernetes/secret.yaml
   
   For production, use Sealed Secrets or External Secrets Operator instead of storing plain-text values in secret.yaml.
3. Deploy Application
   kubectl apply -f deploy/kubernetes/deployment.yaml
   kubectl apply -f deploy/kubernetes/service.yaml
   
4. Verify Deployment
   kubectl get pods -n qwed
   

​

Horizontal Pod Autoscaling (HPA)

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

​

Manual / Bare Metal Deployment

​

1. Prerequisites

​

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install docker.io
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER

​

2. Python Dependencies

# Install dependencies
pip install -e .

​

3. Database Setup

python -c "from qwed_new.core.database import create_db_and_tables; create_db_and_tables()"

​

4. Running the API

# Production Mode with Gunicorn (Linux/macOS)
gunicorn qwed_new.api.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

​

Environment Variables Reference

​

Infrastructure

​

Security Configuration

​

AI Providers

​

Observability

​

Production Checklist

​

1. Database Setup

• Use a managed PostgreSQL instance (e.g., AWS RDS, Azure Database for PostgreSQL).
• Enable automated backups.
• Run database migrations.

​

2. Redis Configuration

• Use a managed Redis instance (e.g., AWS ElastiCache).
• Configure eviction policy (LRU).
• Enable persistence (RDB/AOF).

​

3. Security

• Set API_KEY_SECRET: This is mandatory — generate a secure value with python -c "import secrets; print(secrets.token_urlsafe(48))".
• Set QWED_CORS_ORIGINS: Explicitly list your allowed origins (e.g., https://app.yourcompany.com). The server will not start without this.
• Rotate Keys: Change all default passwords and secrets.
• SSL/TLS: Ensure the API is behind a Load Balancer with a valid SSL certificate.
• Network Policies: Restrict access to database/Redis.
• Docker Security: Ensure the Docker socket is protected or use a secure container runtime (gVisor) for the Stats Verification engine if possible.

​

4. Observability

• Configure alert rules in Prometheus/Grafana.
• Ensure logs are shipped to a centralized logging system.

​

Troubleshooting

​

1. Docker Permission Denied

​

2. Stats or consensus verification returning 503

1. Check Docker is running: docker ps
2. Verify the Docker daemon responds to pings: docker info
3. Check python:3.10-slim image exists: docker pull python:3.10-slim (The executor uses this image).

​

Operations & Monitoring

​

View Recent Security Events

# Python script
python -c "
from qwed_new.core.database import get_session
from qwed_new.core.models import SecurityEvent
from sqlmodel import select

with get_session() as session:
    events = session.exec(
        select(SecurityEvent)
        .where(SecurityEvent.event_type == 'BLOCKED')
        .order_by(SecurityEvent.timestamp.desc())
        .limit(10)
    ).all()
    for e in events:
        print(f'{e.timestamp}: {e.reason}')
"

​

Security Metrics Dashboard

# Block rate by hour
sqlite3 qwed_v2.db "
SELECT strftime('%Y-%m-%d %H:00', timestamp) as hour, COUNT(*) as blocks
FROM security_event
WHERE event_type = 'BLOCKED'
GROUP BY hour
ORDER BY hour DESC
LIMIT 24;
"

• Architecture