system.rk
Layer 2: which backend capabilities are on and which driver serves each. One file per installation: system.rk. App files only say what they need (realtime: true, schedule:, queue:, cache:); this file decides how.
Lives in <site>/system.rk · Schema system.json (source) · first line: # yaml-language-server: $schema=https://rangka-os.github.io/rangka-os/schema/0.5/system.json
Properties
| Property | Type | Meaning |
|---|---|---|
db required | object | Primary database. Always on. |
db.enabled | boolean | default true |
db.driver | postgres | |
db.url | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
db.pool | integer | default 10, min 1, max 200 |
db.isolation | shared · schema · database | shared tables + RLS for small orgs; own schema or database for large ones default "shared" |
cache | object | Read cache for views, dashboards, permission checks. |
cache.enabled | boolean | default true |
cache.driver | memory · valkey | |
cache.url | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
cache.fallback | memory · none | default "memory" |
cache.max_mb | integer | min 8 |
queue | object | Background jobs: actions with queue:, outbound webhooks, connector calls, emails. |
queue.enabled | boolean | default true |
queue.driver | postgres · valkey | |
queue.workers | integer | default 4, min 1, max 256 |
queue.retries | integer | default 3, min 0, max 25 |
queue.dead_letter_after | string | pattern ^[0-9]+(ms|s|m|h|d)$ |
scheduler | object | Cron-style schedules from flows and automations; runs as queue jobs. |
scheduler.enabled | boolean | default true |
scheduler.driver | internal | |
scheduler.timezone | string | default "Asia/Jakarta" |
scheduler.leader_lock | boolean | default true |
realtime | object | Live updates to open screens. Postgres LISTEN/NOTIFY for one node, Valkey pub/sub for many. |
realtime.enabled | boolean | default true |
realtime.driver | postgres · valkey | |
realtime.transports | list of sse · websocket | default ["sse"], at least 1 |
realtime.max_connections | integer | min 1 |
files | object | Attachments, images, exports. |
files.enabled | boolean | default true |
files.driver | local · s3 | |
files.path | string | |
files.bucket | string | |
files.endpoint | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
files.access_key | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
files.secret_key | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
files.max_upload_mb | integer | default 25, min 1 |
search | object | Global search (⌘K) and record search. |
search.enabled | boolean | default true |
search.driver | postgres · opensearch | |
search.vectors | boolean | pgvector embeddings for semantic search default false |
notify | object | Delivery channels. Drivers, not connectors. |
notify.email | object | |
notify.email.enabled | boolean | default true |
notify.email.driver | smtp · log | |
notify.email.host | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
notify.email.port | integer | |
notify.email.username | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
notify.email.password | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
notify.email.from | string | |
notify.push | object | |
notify.push.enabled | boolean | default true |
notify.push.driver | fcm · log | |
notify.push.project | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
notify.push.credentials | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
notify.sms | object | |
notify.sms.enabled | boolean | default true |
notify.sms.driver | log · twilio · zenziva | |
notify.sms.api_key | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
notify.whatsapp | object | |
notify.whatsapp.enabled | boolean | |
notify.whatsapp.connector | string | Uses an installed connector, e.g. whatsapp_business |
auth | object | Rangka ID, built into the kernel: password, passkeys, sessions, API tokens, and an OIDC provider for Omilo and other apps. |
auth.issuer | string | uri |
auth.session_ttl | string | pattern ^[0-9]+(ms|s|m|h|d)$ |
auth.password | boolean or owners | true: everyone signs in with a password. false: nobody does. "owners": only members with role owner (contract 0042 §6). default true |
auth.team | host · kernel | Who manages the team. kernel: owners manage members in Pengaturan → Tim (/api/v1/team). host: the hosting side (Rangka Cloud) does, and /api/v1/team writes answer 403 team_managed_by_host (contract 0056 §5). default "kernel" |
auth.passkeys | boolean | default true |
auth.two_factor | off · optional · owners · everyone | default "owners" |
auth.upstream | list of object | Sign in with an external IdP (per organisation domain routing lives in config.rk). |
auth.upstream[].id required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
auth.upstream[].label | string | |
auth.upstream[].issuer required | string | uri |
auth.upstream[].client_id required | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
auth.upstream[].client_secret | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
auth.clients | list of object | Apps that sign in with Rangka ID (SSO): Omilo, other Rangka installs, partner tools. |
auth.clients[].id required | name | snake_case, never renamed once released pattern ^[a-z][a-z0-9_]{0,62}$ |
auth.clients[].label | string | |
auth.clients[].redirect_uris required | list of string | at least 1 |
auth.clients[].secret | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
auth.clients[].public | boolean | Public clients use PKCE and no secret default false |
auth.clients[].scopes | list of string | |
secrets | object | Where connector secrets and ${VARS} resolve from (contract 0017). env, file and vault are read only; db keeps per-org values set through the write-only API, encrypted with RANGKA_MASTER_KEY. |
secrets.enabled | boolean | default true |
secrets.driver | env · file · vault · db | |
secrets.path | string | file: the directory with one file per ${VAR}; vault: the key path |
connector_auth | object | Binds connector auth fields for the env, file and vault drivers (contract 0017 §2): connector → field → ${VAR}. A secret field must be a ${VAR} reference. orgs.<org> overrides the site's bindings for one organisation. |
connector_auth.orgs | map of map of map of string or number | Per-org bindings: org → connector → field → value |
audit | object | |
audit.enabled | boolean | default true |
audit.retention_days | integer | default 365, min 30 |
observability | object | |
observability.otlp_endpoint | string | A literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys. pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$ |
observability.log_level | debug · info · warn · error | default "info" |
observability.metrics | boolean | default true |
Example
From rangka-apps/examples/sites/kopi-senja/system.rk (first 60 lines):
yaml
# yaml-language-server: $schema=https://rangka-os.github.io/rangka-os/schema/0.5/system.json
# Layer 2: one file per installation. App files say what they need; this file decides how.
db: {driver: postgres, url: '${DATABASE_URL}', pool: 10, isolation: shared}
cache: {driver: memory, max_mb: 64}
queue: {driver: postgres, workers: 4, retries: 3, dead_letter_after: 24h}
scheduler: {driver: internal, timezone: Asia/Jakarta}
realtime: {driver: postgres, transports: [sse]}
files: {driver: local, path: ./data/files, max_upload_mb: 25}
search: {driver: postgres, vectors: false}
notify:
email: {driver: log, from: Kopi Senja <halo@kopisenja.test>}
push: {enabled: false, driver: log}
whatsapp: {enabled: true, connector: whatsapp_business}
auth:
issuer: http://localhost:8080
session_ttl: 24h
two_factor: owners
clients:
- id: omilo
label: Omilo
redirect_uris: [http://localhost:3000/auth/callback]
public: true
scopes: [openid, profile, email, rangka.mcp]
secrets: {driver: env}
audit: {enabled: true, retention_days: 365}
observability: {log_level: info, metrics: true}Generated from the schema by website/scripts/gen-reference.mjs. Edit the schema, not this page.