Skip to content

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 ​

PropertyTypeMeaning
db requiredobjectPrimary database. Always on.
db.enabledboolean
default true
db.driverpostgres
db.urlstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
db.poolinteger
default 10, min 1, max 200
db.isolationshared · schema · databaseshared tables + RLS for small orgs; own schema or database for large ones
default "shared"
cacheobjectRead cache for views, dashboards, permission checks.
cache.enabledboolean
default true
cache.drivermemory · valkey
cache.urlstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
cache.fallbackmemory · none
default "memory"
cache.max_mbinteger
min 8
queueobjectBackground jobs: actions with queue:, outbound webhooks, connector calls, emails.
queue.enabledboolean
default true
queue.driverpostgres · valkey
queue.workersinteger
default 4, min 1, max 256
queue.retriesinteger
default 3, min 0, max 25
queue.dead_letter_afterstring
pattern ^[0-9]+(ms|s|m|h|d)$
schedulerobjectCron-style schedules from flows and automations; runs as queue jobs.
scheduler.enabledboolean
default true
scheduler.driverinternal
scheduler.timezonestring
default "Asia/Jakarta"
scheduler.leader_lockboolean
default true
realtimeobjectLive updates to open screens. Postgres LISTEN/NOTIFY for one node, Valkey pub/sub for many.
realtime.enabledboolean
default true
realtime.driverpostgres · valkey
realtime.transportslist of sse · websocket
default ["sse"], at least 1
realtime.max_connectionsinteger
min 1
filesobjectAttachments, images, exports.
files.enabledboolean
default true
files.driverlocal · s3
files.pathstring
files.bucketstring
files.endpointstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
files.access_keystringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
files.secret_keystringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
files.max_upload_mbinteger
default 25, min 1
searchobjectGlobal search (⌘K) and record search.
search.enabledboolean
default true
search.driverpostgres · opensearch
search.vectorsbooleanpgvector embeddings for semantic search
default false
notifyobjectDelivery channels. Drivers, not connectors.
notify.emailobject
notify.email.enabledboolean
default true
notify.email.driversmtp · log
notify.email.hoststringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
notify.email.portinteger
notify.email.usernamestringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
notify.email.passwordstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
notify.email.fromstring
notify.pushobject
notify.push.enabledboolean
default true
notify.push.driverfcm · log
notify.push.projectstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
notify.push.credentialsstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
notify.smsobject
notify.sms.enabledboolean
default true
notify.sms.driverlog · twilio · zenziva
notify.sms.api_keystringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
notify.whatsappobject
notify.whatsapp.enabledboolean
notify.whatsapp.connectorstringUses an installed connector, e.g. whatsapp_business
authobjectRangka ID, built into the kernel: password, passkeys, sessions, API tokens, and an OIDC provider for Omilo and other apps.
auth.issuerstring
uri
auth.session_ttlstring
pattern ^[0-9]+(ms|s|m|h|d)$
auth.passwordboolean or ownerstrue: everyone signs in with a password. false: nobody does. "owners": only members with role owner (contract 0042 §6).
default true
auth.teamhost · kernelWho 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.passkeysboolean
default true
auth.two_factoroff · optional · owners · everyone
default "owners"
auth.upstreamlist of objectSign in with an external IdP (per organisation domain routing lives in config.rk).
auth.upstream[].id requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
auth.upstream[].labelstring
auth.upstream[].issuer requiredstring
uri
auth.upstream[].client_id requiredstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
auth.upstream[].client_secretstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
auth.clientslist of objectApps that sign in with Rangka ID (SSO): Omilo, other Rangka installs, partner tools.
auth.clients[].id requirednamesnake_case, never renamed once released
pattern ^[a-z][a-z0-9_]{0,62}$
auth.clients[].labelstring
auth.clients[].redirect_uris requiredlist of string
at least 1
auth.clients[].secretstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
auth.clients[].publicbooleanPublic clients use PKCE and no secret
default false
auth.clients[].scopeslist of string
secretsobjectWhere 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.enabledboolean
default true
secrets.driverenv · file · vault · db
secrets.pathstringfile: the directory with one file per ${VAR}; vault: the key path
connector_authobjectBinds 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.orgsmap of map of map of string or numberPer-org bindings: org → connector → field → value
auditobject
audit.enabledboolean
default true
audit.retention_daysinteger
default 365, min 30
observabilityobject
observability.otlp_endpointstringA literal or ${ENV_VAR}. Secrets must use ${…}; the validator refuses literal passwords and keys.
pattern ^(\$\{[A-Z][A-Z0-9_]*\}|[^$].*)$
observability.log_leveldebug · info · warn · error
default "info"
observability.metricsboolean
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.

Rangka OS is source-available under the Elastic License 2.0 (ELv2). Free to self-host.