Deploy & Security Overview

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

Local development

Python venv + uvicorn, or make dev. No database required — the in-memory store works out of the box.

Docker & docker-compose

Single-box production stack: API + Postgres + Caddy (automatic HTTPS) in one docker compose up -d.

Railway

Zero-config PaaS deploy with Nixpacks. Set secrets in the dashboard; railway up handles the rest.

Render

Managed web service with auto-deploy from Git. Free tier available for low-traffic workloads.

Budget VPS (Hetzner, Fly.io, Oracle)

Hetzner CX22 at ~€5/month with Docker Compose + Caddy is the recommended cost-effective option.

Kubernetes

Standard container image with /health (liveness) and /ready (readiness) probes.

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.
`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`.

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

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

Security & compliance docs

Security model

Tenant isolation, envelope encryption, JWT, webhook HMAC, and auth controls.

SOC 2 readiness

Controls in place vs. in-progress, honestly mapped from the readiness audit.

GDPR & data governance

Retention policies, right-to-be-forgotten, tenant data export.

Observability

Health endpoints, structured logging, OTel metrics, and audit trail.

Self-Hosting

Database & Provisioning

Security & Compliance

Deploy & Security Overview

Deployment options at a glance

Local development

Docker & docker-compose

Railway

Render

Budget VPS (Hetzner, Fly.io, Oracle)

Kubernetes

Architecture for operators

Prerequisites for production

Security & compliance docs

Security model

SOC 2 readiness

GDPR & data governance

Observability

​Deployment options at a glance

Local development

Docker & docker-compose

Railway

Render

Budget VPS (Hetzner, Fly.io, Oracle)

Kubernetes

​Architecture for operators

​Prerequisites for production

​Security & compliance docs

Security model

SOC 2 readiness

GDPR & data governance

Observability

Deployment options at a glance

Architecture for operators

Prerequisites for production

Security & compliance docs