Skip to main content
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: Clerk RS256/JWKS for frontend sessions, 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 in mock/offline mode with no Clerk dependency for local development.

​
Prerequisites for production

Before deploying, you need:
RequirementNotes
Python 3.11+Or use the Docker image (Python 3.11-slim)
PostgreSQL 16Neon (managed) or self-hosted. See Database setup.
CAUSELOOP_MASTER_KEY32-byte base64 secret. Required when DATABASE_URL is set.
JWT_SECRETHS256 signing key. Change from the default in production.
Clerk accountRequired only if you use Clerk-based frontend auth (/auth/exchange endpoint).
LLM API keyAnthropic or OpenAI. Omit both to run in offline mock mode.
TLS/HTTPSCaddy 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.