Skip to content
SHC Docs

Configuration

SHC configuration comes from two sources:

  1. Config files: static file-based config loaded at startup (server definitions, pre-DB settings)
  2. Database: user-managed scoped config (runtime settings, feature flags)
interactive: drag or click to explore

Config files are loaded and merged in this order (lowest to highest priority):

  1. default.yaml: bundled vendor defaults (in the package)
  2. /etc/shc/config.yaml: system-wide config
  3. /etc/shc/config.d/*.yaml: system drop-ins (alphabetical order)
  4. ~/.config/shc/config.yaml: user-specific config (non-root only)
  5. dev.yaml: developer overrides (dev mode only)

Config files define named server profiles for the CLI client:

servers:
local:
url: unix:///run/shc/shc.sock
prod:
url: https://prod.example.com
token: ${SHC_PROD_TOKEN}
timeout: 60
tls:
ca: /etc/shc/ca.pem
insecure: false
staging:
url: https://staging.local
tokenExec: pass shc/staging-token
  • ${ENV_VAR}: expands environment variables in string values
  • tokenExec: executes a shell command, uses stdout as the auth token
Terminal window
# Set active server (stored in context.json)
shc ctx --server prod
# Show current context (includes server)
shc ctx

For overlapping keys, the cascade is: CLI flags > env vars > DB config > config files > defaults.

Config files define things needed before the database is available (server URLs, listen address, TLS). Database config handles runtime settings that benefit from scoped inheritance.

Database-backed config resolves through the one SHC scope ladder (core/scope). The most specific wins, always ending at Global:

flowchart TB
G["Global (base)"] --> T["Tenant (tenant)"]
T --> E["Environment (tenant + environment)"]
T --> S["Stack (tenant + stack)"]
S --> D["Deployment (tenant + stack + environment)"]

Stack outranks Environment. Deployment = Stack + Environment together. The same ladder orders vault secret resolution. See config-keys.md § Precedence for the CLI flags that target each tier.

Terminal window
# Global configuration
shc config set backup.retention.daily 7 --scope global
# Tenant-specific
shc config set backup.retention.daily 14 --scope tenant --tenant acme
# Environment-specific
shc config set launcher false --scope environment --tenant acme --environment prod
# Stack-specific
shc config set concurrency.queue_max_depth 2000 --scope stack --tenant acme --stack nextcloud
# Deployment-specific (most specific: tenant + stack + environment)
shc config set launcher false --scope deployment -t acme -s nextcloud -e prod
Terminal window
# Get effective value (with cascade)
shc config get backup.retention.daily
# Get from a specific scope only
shc config get backup.retention.daily --scope tenant --tenant acme
# List all config
shc config ls
shc config ls --scope global
Terminal window
# Backup retention (restic forget policy)
shc config set backup.retention.daily 7 --scope global
shc config set backup.retention.weekly 4 --scope global
# Launcher button (per-app default overridable per scope)
shc config set launcher false --scope tenant --tenant acme
# DNS provider selection
shc config set dns.provider cloudflare --scope global

rate_limit.* cannot be set in the database. shc config set refuses every key under it:

Terminal window
shc config set rate_limit.requests 200 --scope global
# shc: [X400050CFGSTP] config key rate_limit.requests can only be set in yaml config files

Set the block in a drop-in file instead. Each node’s daemon reads its own files and limits its own TCP listener, so write the file on every node:

/etc/shc/config.d/rate-limit.yaml
rate_limit:
requests: 200
window: 30

The daemon watches its config files and applies a changed rate_limit block without a restart. The keys and their defaults are in config-keys.md § rate_limit.

A few keys apply without a daemon restart; most operational changes take effect on the next reconcile / scheduler cycle.

SettingBehavior
rate_limit.*Set in yaml config files only, and on outside dev mode. The daemon reloads the block when those files change; the database store holds no rate_limit value, so it is never consulted.
concurrency.queue_max_depthHot-reloadable.
launcherResolved per request through the scope cascade.
backup.retention.*Applied on the next retention run.
crons.*Applied on the next scheduler cycle.
SettingReason
keycloak.*Auth client wired at startup.
otel.*OTLP exporter (incl. the managed default’s auth) engages on next restart.

Config values can reference vault secrets:

Terminal window
shc config set backup.password 'ref+vault://backup/password' --scope global
shc config set keycloak.client_secret 'ref+vault://keycloak_client_secret' --scope global

A reference is dereferenced when the value is read. For backup.password a reference that cannot resolve (locked vault, absent key) refuses rather than falling back to the literal string, so store the secret first (shc vault set backup/password) and set backup.repo in the same pass: the two are required together.

On a cluster bootstrapped after the backup-key lane you do not do this by hand. shc init seals a generated key (or the one you supplied with --backup-password / --backup-password-file) into the vault at backup/password and points backup.password at it. backup.repo still has no default and is yours to set.

Never edit backup.password to change an in-use key. The row and the repository must change together; editing only the row leaves a repository that opens under a key SHC no longer presents, and every backup fails. Use shc backup key rotate, which does both in one operation and adds the new key before removing the old, so an interruption leaves the repository openable by both rather than neither.