QWED deployment guide

This guide provides instructions for deploying QWED in various environments.

Docker deployment
Kubernetes deployment
Manual / bare metal deployment
Environment variables reference
Production checklist
Troubleshooting
Operations & monitoring

Docker deployment

The easiest way to run QWED locally or on a single server is using Docker Compose.

Dockerfile

A Dockerfile is provided in the root directory. It builds the QWED core service based on python:3.13-slim-bookworm, upgraded from Python 3.12 for reduced CVE exposure.

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

Docker Compose

QWED provides a docker-compose.yml that orchestrates:

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

Before starting the stack, create a .env file in the deploy/ directory with the required environment variables:

# 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

DATABASE_URL, QWED_CORS_ORIGINS, and API_KEY_SECRET are required. Docker Compose will refuse to start if any of these are missing. Generate API_KEY_SECRET with:

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

Start the stack:

docker-compose up -d

Access the services:

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

Docker requirement for code execution

Both the Stats Engine and the Consensus Engine (in high/maximum mode) execute model-generated Python inside Docker containers. Docker is required — there are no in-process fallbacks. If Docker is unavailable, these endpoints return HTTP 503.

Kubernetes deployment

For production environments, QWED ships Kubernetes manifests in deploy/kubernetes/.

Prerequisites

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

Deployment steps

Create Namespace
kubectl create namespace qwed
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.

Deploy Application

kubectl apply -f deploy/kubernetes/deployment.yaml
kubectl apply -f deploy/kubernetes/service.yaml

Verify Deployment
kubectl get pods -n qwed

Horizontal pod autoscaling (HPA)

For high-traffic environments, enable HPA (requires Metrics Server):

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

If you prefer to run the application directly on a host or VM:

1. Prerequisites

Docker Installation (Required for Secure Code Execution) QWED requires Docker for all model-generated code execution in the Stats Engine and Consensus Engine. Without Docker, these verification endpoints return HTTP 503.

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

Ensure PostgreSQL and Redis are running. Set the DATABASE_URL and REDIS_URL environment variables. Initialize the database:

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

Variable	Description	Default	Required
`DATABASE_URL`	Postgres connection string	`sqlite:///./qwed.db`	Yes (Prod)
`REDIS_URL`	Redis connection string	`redis://localhost:6379/0`	Yes (Prod)
`API_KEY_SECRET`	Secret key for signing JWTs	None (must be set)	YES
`QWED_CORS_ORIGINS`	Comma-separated list of allowed CORS origins	None (must be set)	YES
`QWED_SKIP_ENV_INTEGRITY_CHECK`	Set to `true` to bypass startup environment integrity check	`false`	No
`API_KEY_SECRET`	Secret for PBKDF2 API-key hashing	None	Yes
`QWED_CORS_ORIGINS`	Comma-separated allowed CORS origins	None	Yes

API_KEY_SECRET no longer has a default value. The server will refuse to start if it is not set. This prevents accidental deployment with a weak default secret.

Security configuration

Variable	Description	Default
`MAX_INPUT_LENGTH`	Max query length (chars)	2000
`SIMILARITY_THRESHOLD`	Prompt injection detection threshold	0.6
`DOCKER_TIMEOUT`	Code execution timeout (seconds)	10
`DOCKER_MEMORY_LIMIT`	Container memory limit	512m
`QWED_SKIP_ENV_INTEGRITY_CHECK`	Skip `.pth` file verification on startup	`false`

AI providers

Variable	Description	Default
`ACTIVE_PROVIDER`	Selected LLM provider	`azure_openai`
`AZURE_OPENAI_API_KEY`	API key for Azure OpenAI	-
`AZURE_OPENAI_ENDPOINT`	Endpoint URL	-
`ANTHROPIC_API_KEY`	API key for Anthropic	-
`GOOGLE_API_KEY`	API key for Google Gemini (or `GEMINI_API_KEY`)	-
`GEMINI_MODEL`	Gemini model name	`gemini-1.5-pro`

Observability

Variable	Description	Default
`OTEL_EXPORTER_OTLP_ENDPOINT`	Jaeger/OTLP Endpoint	`http://localhost:4317`

Production checklist

Before going to production, ensure the following:

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

Error: docker: Got permission denied while trying to connect to the Docker daemon socket Solution: Ensure the user running the app is in the docker group, or (for Docker Compose) ensure the socket is mounted correctly and the container user has permissions.

2. Stats or consensus verification returning 503

Error: Service temporarily unavailable on /verify/stats or /verify/consensus Cause: The secure Docker sandbox is unreachable. QWED does not fall back to in-process execution. Solution:

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

Operations and 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;
"

For detailed architecture documentation, see:

Architecture

QWED integration troubleshooting

Self-hosting

⌘I

Production path

Deployment

CI/CD

Security & Compliance

Table of contents

Docker deployment

Dockerfile

Docker Compose

Docker requirement for code execution

Kubernetes deployment

Prerequisites

Deployment steps

Horizontal pod autoscaling (HPA)

Manual / bare metal deployment

1. Prerequisites

Linux (Ubuntu/Debian)

2. Python dependencies

3. Database setup

4. Running the API

Environment variables reference

Infrastructure

Security configuration

AI providers

Observability

Production checklist

1. Database setup

2. Redis configuration

3. Security

4. Observability

Troubleshooting

1. Docker permission denied

2. Stats or consensus verification returning 503

Operations and monitoring

View recent security events

Security metrics dashboard

​Table of contents

​Docker deployment

​Dockerfile

​Docker Compose

​Docker requirement for code execution

​Kubernetes deployment

​Prerequisites

​Deployment steps

​Horizontal pod autoscaling (HPA)

​Manual / bare metal deployment

​1. Prerequisites

​Linux (Ubuntu/Debian)

​2. Python dependencies

​3. Database setup

​4. Running the API

​Environment variables reference

​Infrastructure

​Security configuration

​AI providers

​Observability

​Production checklist

​1. Database setup

​2. Redis configuration

​3. Security

​4. Observability

​Troubleshooting

​1. Docker permission denied

​2. Stats or consensus verification returning 503

​Operations and monitoring

​View recent security events

​Security metrics dashboard

Table of contents

Docker deployment

Dockerfile

Docker Compose

Docker requirement for code execution

Kubernetes deployment

Prerequisites

Deployment steps

Horizontal pod autoscaling (HPA)

Manual / bare metal deployment

1. Prerequisites

Linux (Ubuntu/Debian)

2. Python dependencies

3. Database setup

4. Running the API

Environment variables reference

Infrastructure

Security configuration

AI providers

Observability

Production checklist

1. Database setup

2. Redis configuration

3. Security

4. Observability

Troubleshooting

1. Docker permission denied

2. Stats or consensus verification returning 503

Operations and monitoring

View recent security events

Security metrics dashboard