Configuration

The environment is the config

Uruk reads everything from URUK_* environment variables at startup — no committed .env, no settings file to fork, no per-site configuration at all. Per-site state lives in the database like everything else; the environment only tells the process where that database is and how to behave. A process holding nothing but database credentials boots, migrates, seeds this site, and serves.

Claiming the first superuser

A fresh tenant has no users, so there is nobody to log in as. The one-shot bootstrap endpoint solves this: POST /api/bootstrap with an email creates the tenant's first superuser and returns a single-use set-password link. Because the link goes to whoever asks, the claim also needs the tenant's claim code, derived from the secret key so that only the operator can read it: manage.py bootstrap prints it in the server logs while the tenant is unclaimed, and manage.py claim_code prints it on demand. Set URUK_ADMIN_EMAIL and only that address is honoured as well. Once a superuser exists, the endpoint refuses forever — from then on, only an existing superuser can create another.

The rule is per tenant: every newly created tenant starts unclaimed, and its first superuser is caught the same way on its own domain. The walkthrough lives on the quickstart page.

Core

VariableDefaultPurpose
URUK_DEBUGFalseDjango debug mode. Keep it off anywhere real.
URUK_ENVunknownFree-form environment label — production, staging, a laptop.
URUK_SECRET_KEYinsecure dev keySigns sessions and JWTs. Set at least 32 bytes in production.
URUK_ALLOWED_HOSTS*Comma-separated Host allowlist. Uruk routes by hostname, so the catch-all default is deliberate.
URUK_BEHIND_PROXYFalseHTTPS ends at a proxy (Cloudflare Tunnel, Caddy, a load balancer): trust its X-Forwarded-Proto and mark cookies Secure. Enable only when the proxy is the sole way in.
URUK_CSRF_TRUSTED_ORIGINSemptyExtra scheme://host origins allowed to post forms, for proxies that rewrite the Host.

Database

VariableDefaultPurpose
URUK_DB_HOST127.0.0.1Postgres host. One database holds every tenant, each in its own schema.
URUK_DB_PORT5433Postgres port — matches the port the bundled compose file publishes.
URUK_DB_NAMEurukDatabase name.
URUK_DB_USERurukDatabase user.
URUK_DB_PASSWORDurukDatabase password.
URUK_DB_POOLTrueNative psycopg3 connection pooling — no external pooler needed.

Cache & asset storage

By default one Postgres holds everything — computed pages cache in a shared table, asset bytes live in rows. Two variables opt out when scale demands it.

VariableDefaultPurpose
URUK_REDIS_URLunsetPoint at Redis and the page/fragment cache moves there. Unset, it lives in Postgres.
URUK_STORAGE_BACKENDunsetWhere asset bytes live: unset = in the database; filesystem or boto move the bytes out (rows and hashes stay).
URUK_STORAGE_ROOT—Filesystem backend: directory for the bytes.
URUK_STORAGE_BUCKET—Boto backend: S3-compatible bucket.
URUK_STORAGE_PREFIX—Boto backend: key prefix inside the bucket.
URUK_STORAGE_ENDPOINT_URL—Boto backend: custom endpoint (MinIO, R2, …).
URUK_STORAGE_REGION—Boto backend: bucket region.

Server

Read by docker-entrypoint.sh, which forwards each to Granian — the Rust HTTP server Uruk ships on — as the matching GRANIAN_* option. The defaults are the production configuration; set a variable only to depart from them. Any other Granian option can be set directly as GRANIAN_*.

VariableDefaultPurpose
URUK_WORKERS2Worker processes. Each holds its own connection pool — keep workers × pool size under Postgres max_connections.
URUK_BLOCKING_THREADS8Request threads per worker — keep close to the connection pool's max size.
URUK_BACKPRESSURE16Maximum in-flight requests per worker.
URUK_RESPAWN_FAILED_WORKERStrueA worker that crashes comes back on its own.
URUK_WORKERS_LIFETIME3600Recycle each worker after this many seconds.
URUK_WORKERS_MAX_RSS512Recycle a worker as soon as its memory exceeds this many MiB.

Bootstrap

VariableDefaultPurpose
URUK_DEFAULT_TENANT_SCHEMAdefaultSchema name of the catch-all tenant — the one serving this page to any unmatched hostname.
URUK_DEFAULT_TENANT_DOMAINdefault.localhostPlaceholder primary domain recorded for it. Routing to the default tenant is by fallback, not by matching this string.
URUK_DEFAULT_SITEshowcaseWhat the default tenant starts with: showcase (this website) or blank (one empty landing page to fill in).
URUK_ADMIN_EMAILemptyRestrict the first-superuser claim to this address, on top of the claim code. Empty = any address.
URUK_ADMIN_PATHurukURL prefix of the Django admin and its login page. Off the well-known /admin/; it shadows a page with the same top-level slug.

JWT

VariableDefaultPurpose
URUK_JWT_ACCESS_TTL900Access-token lifetime, seconds (15 minutes).
URUK_JWT_REFRESH_TTL1209600Refresh-token lifetime, seconds (14 days).

Observability

The one family that keeps its standard names: the OpenTelemetry SDK reads OTEL_* variables itself, so Uruk does not rename them. The rule stays the same — nothing loads unless configured. Without an endpoint the SDK is never even imported; with one, requests, database and cache activity are traced, and every request span carries the resolved tenant schema as uruk.tenant.

VariableDefaultPurpose
OTEL_EXPORTER_OTLP_ENDPOINTunsetThe gate. Point at an OTLP/HTTP collector and tracing turns on; unset, telemetry costs nothing.
OTEL_SERVICE_NAMEurukService name on exported spans.
any other OTEL_*—Headers, sampling, resource attributes — every standard OpenTelemetry SDK variable applies as-is.

MCP

Read by the MCP server process — the agent's stdio bridge — not by Django itself.

VariableDefaultPurpose
URUK_MCP_TENANT—Tenant schema the agent works in.
URUK_MCP_TOKEN—The uruk_… API token it authenticates with; the agent gets exactly that user's permissions.