Configuration

One contract for every environment

A document configures exactly one Realm or Fleet control-plane process. Keep one file per environment so production cannot silently inherit development policy, and review changes alongside deployment code.

deploy/
  development/rustyauth.yaml
  staging/rustyauth.yaml
  production/rustyauth.yaml

Unknown fields, kinds and API versions are rejected. Durations use readable values such as 30s, 5m, 6h, 7d and 90d.

Realm example

apiVersion: rustyauth.dev/v1alpha1
kind: Realm
metadata:
  tenantId: payments
  realmId: payments-production
spec:
  environment: production
  server:
    bind: 0.0.0.0
    port: 8080
    publicIssuer: https://auth.example.com
    trustedProxyHops: 1
  datastore:
    endpoint: redis://sabledb.railway.internal:6379
  relyingParty:
    id: app.example.com
    origin: https://app.example.com
    name: Example Account
  tokens:
    audience: payments-api
    accessTtl: 5m
  sessions:
    idleTimeout: 30m
    absoluteTimeout: 7d
  webhooks:
    - id: application-lifecycle
      name: Application lifecycle
      endpoint: https://api.example.com/hooks/rustyauth
      enabled: true
      eventTypes:
        - identity.created
        - session.created
  backups:
    enabled: false

What IaC owns

The application document complements Terraform, Pulumi, Railway or Compose; it does not replace them. Credentials and user state never belong in committed YAML.

Generate and validate

rustyauth config example realm > rustyauth.yaml
rustyauth config validate rustyauth.yaml
rustyauth --config rustyauth.yaml

config validate uses the same parser and policy checks as service startup, but substitutes non-credential validation material so pull-request jobs do not need production secrets. Its JSON summary omits datastore details and every credential.

for config in deploy/*/rustyauth.yaml; do
  rustyauth config validate "$config"
done

The checked-in JSON Schema provides editor completion. Start from the local example or the production example with backups and webhooks.

Configuration source precedence

Configure only one of RUSTYAUTH_CONFIG_YAML and RUSTYAUTH_CONFIG_FILE. An explicit --config path wins because it is an operator action for that invocation.

Docker and Kubernetes

The container automatically loads /etc/rustyauth/config.yaml; no wrapper entrypoint is required.

services:
  auth:
    image: ghcr.io/rusty-auth/rustyauth:v1.0.0
    configs:
      - source: rustyauth
        target: /etc/rustyauth/config.yaml
    environment:
      AUTH_MASTER_KEY_HEX_FILE: /run/secrets/master-key
      BOOTSTRAP_TOKEN_FILE: /run/secrets/bootstrap-token

configs:
  rustyauth:
    file: ./deploy/production/rustyauth.yaml

On Kubernetes, mount the document from a ConfigMap at the same path and expose credentials from Secret objects through fixed environment names or their _FILE companions.

Railway

Set the complete document as the multiline RUSTYAUTH_CONFIG_YAML service variable. Railway's injected PORT overrides spec.server.port, and a private SABLEDB_URL service reference may replace a credential-bearing datastore endpoint. Keep generated keys and tokens as separate sealed variables.

railway.json still owns build, health, replica and restart policy. The RustyAuth YAML owns application behavior, so the same document remains understandable outside Railway. Continue with the deployment guide.

Secrets stay separate

Every secret accepts a corresponding _FILE input for container secret mounts. Supplying both forms for the same value is rejected. Backup credentials are required only when the YAML enables backups; Fleet control planes do not require the Realm event and identity RPC tokens.

IaC-managed webhooks

Realm documents can declare stable webhook IDs, HTTPS endpoints, enabled state and event types under spec.webhooks. These resources are authoritative, not initial defaults. API responses identify their management source, and the dashboard labels them Managed by YAML, disables destination controls and directs operators back to the deployment file. Dashboard-created destinations remain dashboard-managed.

This single-writer rule prevents UI edits from being silently reversed on the next deploy. Operational actions such as testing, delivery inspection and signing-secret rotation remain separate from desired-state ownership.

Backup schedules

backups:
  enabled: true
  destination:
    endpoint: https://s3.eu-west-2.amazonaws.com
    region: eu-west-2
    bucket: example-rustyauth-backups
    storageProfile: immutable
    serverSideEncryption:
      mode: aws-kms
      kmsKeyId: arn:aws:kms:eu-west-2:123456789012:key/<key-id>
  schedule:
    interval: 6h
    recoveryPointObjective: 6h
  retention: 90d
  alertAfterFailures: 2

Storage credentials and the portable encryption key remain secret inputs. The default immutable profile requires the bucket to enforce Versioning, compliance-mode Object Lock and the configured provider-side encryption policy. The explicit portable profile retains application encryption and read-back verification for providers without those APIs, but does not claim WORM retention.

Continue to Backups and disaster recovery for snapshot coverage, the binary .rauth format, S3 verification, alerting and the clean-room restore procedure.

Complete reference

Use the repository's normative configuration reference for every field, validation bound, legacy environment variable and deployment caveat. The application and CLI use the same parser described there.