File locations

SHC uses a minimal set of directories with XDG-compliant path resolution.

User Installation (non-root)

Type	Path
Config	`~/.config/shc/`
State	`~/.local/share/shc/`
Cache	`~/.cache/shc/`
Runtime	`$XDG_RUNTIME_DIR/shc/` or `/tmp/shc-{uid}`
Logs	`~/.local/share/shc/logs/`

System Installation (root)

Type	Path
Config	`/etc/shc/`
State	`/var/lib/shc/`
Cache	`/var/cache/shc/`
Runtime	`/run/shc/`
Logs	`/var/log/shc/`

Dev Mode

When running from source:

{project_root}/.shc/
├── state/
├── cache/
├── run/
└── logs/

Key Files

File	Path	Purpose
SQLite DB	`{state_home}/shc.db`	Database (single-node)
rqlite dir	`{state_home}/rqlite/`	Raft engine data (cluster mode)
PID file	`{runtime_dir}/shc.pid`	Server process ID
Socket	`{runtime_dir}/shc.sock`	CLI-server IPC
Global log	`{logs_dir}/shc.log`	System-wide logging

Database Modes

SHC supports two database modes (mutually exclusive):

Mode	Storage	Detection
Single-node	`{state_home}/shc.db`	Default
Cluster	`{state_home}/rqlite/`	`{state_home}/engine.json` exists

Cache Directories

Directory	Path	Purpose
Git cache	`{cache_home}/git/{url_hash}/`	Cloned git repos for install

When installing apps from git URLs, repositories are cloned to the cache:

{cache_home}/git/
└── {url_hash}/
    ├── .git/
    ├── app.yaml
    ├── compose.yaml
    └── ...

The url_hash is a SHA-256 hash of the normalized git URL.

Deployment State (Storage Providers)

Deployment state is managed by storage providers, not static paths. The location depends on the configured provider:

Provider	Base Path
Local	`/var/lib/shc` (or configured path)
NFS	`/mnt/shc/nfs`
CephFS	`/mnt/shc/cephfs`

NFS and CephFS paths are fixed for the managed singletons. Local providers can point at any mount you register with shc storage add --path ....

Structure within:

{provider_base_path}/{tenant}/{stack}/{environment}/
├── compose/    # Generated compose files
├── mounts/     # DATA mounts (persistent, backed up)
├── files/      # FILE mounts (regenerated on install)
└── app/        # App definition

Configuration Files

Config files are loaded and merged (see Config Files):

Path	Purpose
`/etc/shc/config.yaml`	System-wide config
`/etc/shc/config.d/*.yaml`	System drop-ins
`~/.config/shc/config.yaml`	User config (non-root)

Runtime config is stored in the database and managed via CLI:

shc config set backup.retention_days 30 --scope global
shc config set backup.retention_days 14 --scope tenant

Backups

Backups go to Restic or user-specified paths, not a fixed directory:

# To Restic (configured via backup.repo)
shc backup create mystack

# To explicit path
shc backup create mystack --file /path/to/backup.bak