> ## Documentation Index
> Fetch the complete documentation index at: https://docs.causeloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy & Security Overview

> Deployment options, architecture for operators, and prerequisites for running Causeloop in production.

Causeloop is a Python 3.11 / FastAPI service that connects to a PostgreSQL database and optional LLM providers. You can run it anywhere a container or Python process runs. This section covers everything an operator needs: environment configuration, local development, Docker, managed platforms (Railway, Render), and the security and compliance story.

## Deployment options at a glance

<CardGroup cols={2}>
  <Card title="Local development" icon="laptop-code" href="/deploy-security/local-development">
    Python venv + uvicorn, or `make dev`. No database required — the in-memory store works out of the box.
  </Card>

  <Card title="Docker & docker-compose" icon="docker" href="/deploy-security/docker">
    Single-box production stack: API + Postgres + Caddy (automatic HTTPS) in one `docker compose up -d`.
  </Card>

  <Card title="Railway" icon="train" href="/deploy-security/deploy#railway">
    Zero-config PaaS deploy with Nixpacks. Set secrets in the dashboard; `railway up` handles the rest.
  </Card>

  <Card title="Render" icon="cloud" href="/deploy-security/deploy#render">
    Managed web service with auto-deploy from Git. Free tier available for low-traffic workloads.
  </Card>

  <Card title="Budget VPS (Hetzner, Fly.io, Oracle)" icon="server" href="/deploy-security/deploy#budget-hosting">
    Hetzner CX22 at \~€5/month with Docker Compose + Caddy is the recommended cost-effective option.
  </Card>

  <Card title="Kubernetes" icon="cubes" href="/deploy-security/docker#kubernetes">
    Standard container image with `/health` (liveness) and `/ready` (readiness) probes.
  </Card>
</CardGroup>

## Architecture for operators

```
                    ┌─────────────────────────────────────────┐
                    │               Internet                   │
                    └──────────────────┬──────────────────────┘
                                       │ TLS 1.3
                    ┌──────────────────▼──────────────────────┐
                    │        Caddy (reverse proxy)             │
                    │   Auto Let's Encrypt · HSTS · gzip       │
                    └──────────────────┬──────────────────────┘
                                       │ HTTP :4000
                    ┌──────────────────▼──────────────────────┐
                    │     FastAPI / Uvicorn  (app.main:app)    │
                    │  CORS · Rate limit · Idempotency-Key     │
                    │  JWT auth · RBAC · 34 domain routers     │
                    └──────┬──────────────────────────────────-┘
                           │                       │
               ┌───────────▼──────┐     ┌──────────▼─────────┐
               │  PostgreSQL 16   │     │  LLM providers      │
               │  RLS · Audit log │     │  Anthropic / OpenAI │
               │  Envelope enc.   │     │  (or mock fallback) │
               └──────────────────┘     └────────────────────┘
```

**Key properties:**

* **Multi-tenancy:** every data row is scoped to a `workspace_id`. Row-Level Security (RLS) enforced at the database level means one tenant can never read another's data, even if application logic is bypassed.
* **Envelope encryption:** secrets stored in the database (connector configs, webhook secrets, MFA factors) are protected by AES-256-GCM using a per-workspace data key (DEK) wrapped by a master key (`CAUSELOOP_MASTER_KEY`) that never touches the database.
* **Auth:** RS256/JWKS verification of upstream identity provider tokens (WorkOS AuthKit by default; pluggable to Auth0/Okta/generic OIDC via `AUTH_PROVIDER`) exchanged for HS256 Causeloop JWTs, HS256 JWTs for service-to-service, SHA-256-hashed personal access tokens (PATs). All scoped via a typed RBAC permission catalogue.
* **No single point of failure for auth:** the app can run with `AUTH_PROVIDER=none` (mock/offline mode) with no external identity-provider dependency for local development.

## Prerequisites for production

Before deploying, you need:

| Requirement                                           | Notes                                                                                                                   |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Python 3.11+                                          | Or use the Docker image (Python 3.11-slim)                                                                              |
| PostgreSQL 16                                         | Neon (managed) or self-hosted. See [Database setup](/deploy-security/database).                                         |
| `CAUSELOOP_MASTER_KEY`                                | 32-byte base64 secret. **Required when `DATABASE_URL` is set.**                                                         |
| `JWT_SECRET`                                          | HS256 signing key. Change from the default in production.                                                               |
| WorkOS account (`WORKOS_CLIENT_ID`, `WORKOS_API_KEY`) | Required only if you use WorkOS-based frontend auth (`/auth/exchange` endpoint). Omit to run with `AUTH_PROVIDER=none`. |
| LLM API key                                           | Anthropic or OpenAI. Omit both to run in offline mock mode.                                                             |
| TLS/HTTPS                                             | Caddy handles this automatically. Required for `Strict-Transport-Security`.                                             |

<Warning>
  Never run production with `JWT_SECRET=dev-secret-change-me`. Generate a strong secret:

  ```bash theme={null}
  python3 -c "import secrets; print(secrets.token_urlsafe(48))"
  ```
</Warning>

## Security & compliance docs

<CardGroup cols={2}>
  <Card title="Security model" icon="shield-halved" href="/deploy-security/security-model">
    Tenant isolation, envelope encryption, JWT, webhook HMAC, and auth controls.
  </Card>

  <Card title="SOC 2 readiness" icon="clipboard-check" href="/deploy-security/soc2">
    Controls in place vs. in-progress, honestly mapped from the readiness audit.
  </Card>

  <Card title="GDPR & data governance" icon="scale-balanced" href="/deploy-security/gdpr-governance">
    Retention policies, right-to-be-forgotten, tenant data export.
  </Card>

  <Card title="Observability" icon="chart-line" href="/deploy-security/observability">
    Health endpoints, structured logging, OTel metrics, and audit trail.
  </Card>
</CardGroup>