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.
Core
| Variable | Default | Purpose |
|---|---|---|
| URUK_DEBUG | False | Django debug mode. Keep it off anywhere real. |
| URUK_ENV | unknown | Free-form environment label — production, staging, a laptop. |
| URUK_SECRET_KEY | insecure dev key | Signs 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_PROXY | False | HTTPS 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_ORIGINS | empty | Extra scheme://host origins allowed to post forms, for proxies that rewrite the Host. |
Database
| Variable | Default | Purpose |
|---|---|---|
| URUK_DB_HOST | 127.0.0.1 | Postgres host. One database holds every tenant, each in its own schema. |
| URUK_DB_PORT | 5433 | Postgres port — matches the port the bundled compose file publishes. |
| URUK_DB_NAME | uruk | Database name. |
| URUK_DB_USER | uruk | Database user. |
| URUK_DB_PASSWORD | uruk | Database password. |
| URUK_DB_POOL | True | Native 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.
| Variable | Default | Purpose |
|---|---|---|
| URUK_REDIS_URL | unset | Point at Redis and the page/fragment cache moves there. Unset, it lives in Postgres. |
| URUK_STORAGE_BACKEND | unset | Where 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_*.
| Variable | Default | Purpose |
|---|---|---|
| URUK_WORKERS | 2 | Worker processes. Each holds its own connection pool — keep workers × pool size under Postgres max_connections. |
| URUK_BLOCKING_THREADS | 8 | Request threads per worker — keep close to the connection pool's max size. |
| URUK_BACKPRESSURE | 16 | Maximum in-flight requests per worker. |
| URUK_RESPAWN_FAILED_WORKERS | true | A worker that crashes comes back on its own. |
| URUK_WORKERS_LIFETIME | 3600 | Recycle each worker after this many seconds. |
| URUK_WORKERS_MAX_RSS | 512 | Recycle a worker as soon as its memory exceeds this many MiB. |
Bootstrap
| Variable | Default | Purpose |
|---|---|---|
| URUK_DEFAULT_TENANT_SCHEMA | default | Schema name of the catch-all tenant — the one serving this page to any unmatched hostname. |
| URUK_DEFAULT_TENANT_DOMAIN | default.localhost | Placeholder primary domain recorded for it. Routing to the default tenant is by fallback, not by matching this string. |
| URUK_DEFAULT_SITE | showcase | What the default tenant starts with: showcase (this website) or blank (one empty landing page to fill in). |
| URUK_ADMIN_EMAIL | empty | Restrict the first-superuser claim to this address, on top of the claim code. Empty = any address. |
| URUK_ADMIN_PATH | uruk | URL 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
| Variable | Default | Purpose |
|---|---|---|
| URUK_JWT_ACCESS_TTL | 900 | Access-token lifetime, seconds (15 minutes). |
| URUK_JWT_REFRESH_TTL | 1209600 | Refresh-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.
| Variable | Default | Purpose |
|---|---|---|
| OTEL_EXPORTER_OTLP_ENDPOINT | unset | The gate. Point at an OTLP/HTTP collector and tracing turns on; unset, telemetry costs nothing. |
| OTEL_SERVICE_NAME | uruk | Service 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.
| Variable | Default | Purpose |
|---|---|---|
| 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. |