Skip to main content

Config Hierarchy

Configuration is resolved in this priority order (highest wins):

1. CLI flags           --port 8081
2. Environment vars    ARCAN_PORT=8081
3. Config file         ~/.arcan/config.yaml or /etc/arcan/config.yaml
4. Defaults            Hardcoded in code

Environment Variable Convention​

  • Prefix: ARCAN_
  • Uppercase with underscores
  • Nested keys use double underscore: ARCAN_STORE__TYPE=postgres

Config File Locations​

Config file format is YAML only. Located at:

  • ~/.arcan/config.yaml -- user-level, Standalone default
  • /etc/arcan/config.yaml -- system-level, production default
  • Override with --config /path/to/config.yaml or ARCAN_CONFIG=/path/to/config.yaml

Full YAML Config Example​

# Server
server:
    port: 8081
    host: "0.0.0.0"
    tls:
        cert_file: ""              # auto-generated self-signed if empty
        key_file: ""               # provide real certs for production

# Storage
store:
    type: sqlite                    # sqlite | postgres
    # SQLite-specific
    path: "~/.arcan/data/arcan.db"
    # PostgreSQL-specific
    dsn: ""                         # or use DATABASE_URL env var

# Encryption
encryption:
    master_key:
        source: file                # file | aws_kms | gcp_kms | azure_kv
        aws_kms_key_id: ""
        aws_region: ""
        gcp_kms_key: ""
        azure_vault_url: ""
        azure_key_name: ""
        s3_bucket: ""
        s3_endpoint: ""

# Auth
auth:
    token_ttl: 720h                 # default API token TTL (30 days)
    session_ttl: 24h                # default session TTL

# Audit
audit:
    retention_days: 90              # auto-cleanup after N days (0 = never)
    sinks: []                       # configured in runtime via API

# Plugins
plugins:
    directory: "~/.arcan/plugins"   # where plugin binaries live
    registry_url: "https://registry.getarcan.dev"
    auto_update: false              # auto-update plugins on startup
    # Per-plugin config
    postgres:
        max_connections: 10
        default_ttl: 1h
    aws:
        region: us-east-1

# Reaper (background cleanup)
reaper:
    enabled: true
    interval: 60s                   # how often the reaper runs
    lease_grace_period: 5m          # extra time before revoking expired leases

Validation Rules​

  • No plaintext secrets in config files. Use env vars (DATABASE_URL, ARCAN_KMS_KEY_ID) or KMS references.
  • Config is validated at startup. Invalid config results in an immediate exit with a clear error message.
  • Unknown config keys are warnings, not errors (forward compatibility).