Skip to content
SHC Docs

Data model

Layer 6. Services. Services

A deployment is the running unit. One row in deployment is one running app (ce ent/schema/deployment.go). The row has no name of its own. Stack and environment are the axes, with the tenant:

  • Tenant (tenant_name): which tenant the deployment belongs to.
  • Stack (stack_name): the name axis. shc install nextcloud uses the app name unless --stack sets another.
  • Environment (environment): the other axis. Unset folds to default (ce core/scope/scope.go, DefaultName).

The app is app_name. Two deployments may share a stack name and differ by environment, or share an environment and differ by stack name.

The on-disk directory is {state_home}/deployments/{tenant}/{stack}/{environment} (ce modules/app/install_runner.go, DeploymentDir).

Config walks one ladder, narrowest first: deployment, stack, environment, tenant, global (ce core/scope/scope.go, Cascade). Stack outranks environment.

See Deployment identity.

Environment is an axis of the deployment. Common environment names:

EnvironmentPurpose
defaultDefault when not specified
prodProduction workloads
stagingPre-production testing
devDevelopment and experimentation
Terminal window
# Override config for specific environment
shc config set backup.retention.daily 14 --scope stack -t acme -s myblog
shc config set deploy.memory_quota 4g --scope deployment -t acme -s myblog -e prod
AspectShared Between Environments?
App definitionYes (same app.yaml, compose.yaml)
Data volumesNo (each env has own mounts/ directory)
ConfigInherited but can be overridden per-env
Vault secretsCan be scoped to environment or shared
Docker networkNo (each env has own network)
Container namesNo (each deployment has its own)

SHC uses a minimal set of directories, following XDG conventions on Linux:

DirectoryLinuxmacOS (Darwin)BSD
state_home/var/lib/shc/var/lib/shc/var/lib/shc
cache_home/var/cache/shc/var/cache/shc/var/cache/shc
runtime_dir/run/shc/var/run/shc/var/run/shc
logs_dir/var/log/shc/var/log/shc/var/log/shc
DirectoryAll Platforms (XDG)
config_home~/.config/shc
state_home~/.local/share/shc
cache_home~/.cache/shc
runtime_dir$XDG_RUNTIME_DIR/shc or /tmp/shc-{uid}
logs_dir~/.local/share/shc/logs

When running from source (go.mod detected), all paths consolidate under the project:

{project_root}/.shc/
├── state/
├── cache/
├── run/
└── logs/
  • Config paths - Configuration is stored in the database, not files
  • Backup paths - Backups go to Restic or user-specified paths

Deployment state paths ARE in paths.go: DeploymentsDir() returns <state_home>/deployments, unconditionally. They are not provider-dependent; shc install --storage records a label and does not relocate anything. See the storage module.


# State
{state_home}/
├── shc.db # SQLite database (single-node)
├── engine.json # engine marker (present in cluster mode)
├── node.id # this node's cluster member id
├── deployments/ # per-deployment trees (DeploymentsDir())
└── rqlite/ # rqlited data (cluster mode: raft log + snapshots)
# Logs (scoped hierarchy, each node has its own logs)
{logs_dir}/
├── shc.log # Global log
└── tenants/{tenant}/
└── stacks/{stack}/
└── environments/{environment}/
└── shc.log # Deployment log
# Runtime (ephemeral, cleared on reboot)
{runtime_dir}/
├── shc.pid # Server PID file
└── shc.sock # Unix socket
# Cache (can be deleted anytime)
{cache_home}/
└── git/ # Cloned git repositories
└── {url_hash}/ # Hashed repo URL

Deployment state lives under the node’s own state home, always. app.DeploymentDir joins {state_home}/deployments/{tenant}/{stack}/{environment} with no provider in the expression, and panics rather than fall back when the state home is empty. shc install --storage <name> records a label on the deployment row; it does not change this path. See the storage module for what the label does affect.

{state_home}/deployments/{tenant}/{stack}/{environment}/
├── manifest.json # the SOLE on-disk state file (ADR-0002); 0600
├── rendered.sealed # the rendered documents, sealed with the node's vault; 0600
├── app/ # app definition (copied from the repo)
│ ├── app.yaml
│ ├── compose.yaml
│ └── vars.yaml
├── mounts/ # DATA mounts (BACKED UP)
│ ├── pgdata/
│ └── uploads/
├── files/ # FILE mounts (re-rendered on install)
├── runtime/ # RUNTIME mounts (scratch, tmpfs-like)
└── vapps/{instance}/ # per-vApp-instance state, each with its own manifest.json

manifest.json holds the install-time spec (the flags, -i integrations, -c bindings, ports and --var overrides an update replays), and it is node-local, never raft-replicated; the deployment table stays the cluster-consistent authority for listing and scheduling. A non---data uninstall removes every rendered entry above and keeps only mounts/ and vapps/, so dropping manifest.json is what de-registers the deployment from the on-disk lookup chain. files/, runtime/ and vapps/ appear only when the app declares FILE mounts, RUNTIME mounts, or vApp instances respectively.

manifest.json is the only sidecar (ce modules/app/manifest.go). A directory that still has only the old name is not read (X404014MANNOF).

The documents the engine runs hold resolved vault values, so they are kept in RAM, never in the deployment directory: the rendered compose.yaml, its compose.running.yaml copy and the replicas/ and incarnations/ projects sit at the directory’s own path below {secrets_ram_root}/.rendered (/run/shc-secrets/.rendered/var/lib/shc/deployments/... on a Linux node). The directory keeps rendered.sealed, the same documents sealed with the node’s vault, and the compose project directory stays the deployment directory, so relative binds resolve as before. manifest.json still records compose_path as {deployment dir}/compose.yaml; readers open it in RAM (ce core/paths/rendered.go).

After a reboot the RAM is empty. shcd opens each seal once the vault unlocks and puts the documents back, and the node agent starts nothing until it has (X503943RNDLCK names a deployment still waiting). A node whose vault auto-unlocks at boot comes back with no human step; one that does not waits for shc vault unlock. A directory an earlier release left with plaintext documents is moved into RAM and sealed the first time the new shcd starts, and the plaintext copy goes only after the seal is written, synced and read back.

The same root holds the other files that carry resolved values. A deployment’s staged configs sit at its directory’s path below {secrets_ram_root}/.configs (ce core/paths/staged_configs.go). One run’s files, a job’s or a backup hook’s compose, the converter’s and the env file an exec hands the engine, go in a directory of their own below {secrets_ram_root}/.scratch that the run removes when it ends (ce core/secretscratch). Where RAM does not back that root the run refuses and writes nothing. The registry logins an engine pulls with are there too: the node’s composed login at {secrets_ram_root}/.registry/node (the engine’s DOCKER_CONFIG) and each tenant’s under .registry/tenants (ce core/paths/registry_auth.go). After a reboot shcd composes the node’s login once the vault opens, before it puts the rendered documents back. A node upgraded from v0.1.21 keeps using {state_home}/registry until then, and that copy is removed once the login in RAM is in use.

ModeDatabasePath
Single-nodeSQLite (pure-Go, file + WAL){state_home}/shc.db
Clusterrqlite (external rqlited process){state_home}/rqlite/

Cluster mode is detected by the presence of the {state_home}/engine.json marker; the daemon then supervises rqlited and swaps its pool to the raft-replicated engine at boot.

All configuration is stored in the database, not in files:

  • Single-node: Config table in SQLite
  • Cluster: Config table in rqlite (raft-replicated across nodes)

Config walks deployment, then stack, then environment, then tenant, then global (ce core/scope/scope.go).

Backups are not stored in a fixed location. They either:

  • Go to Restic (configured via backup.repo)
  • Go to an explicit path specified by the user

FilePathPurpose
SQLite DB{state_home}/shc.dbDatabase (single-node)
rqlite dir{state_home}/rqlite/Database (cluster)
Engine marker{state_home}/engine.jsonCluster-engine flag
PID file{runtime_dir}/shc.pidServer process ID
Unix socket{runtime_dir}/shc.sockCLI-server communication
Global log{logs_dir}/shc.logSystem-wide log
Deployment log{logs_dir}/tenants/.../shc.logPer-deployment log
Git cache{cache_home}/git/Cloned git repositories

TypeExampleLocationBacked Up
DATApgdata:/var/lib/postgresqlmounts/pgdata/✅ Yes
FILE./config.yaml:/app/config.yamlfiles/config.yaml❌ No (part of app)
RUNTIMEtmp:/cache/tmp/...❌ No (ephemeral)
SYSTEM/var/run/docker.sockunchanged❌ No (host path)

The mounts/ directory contains persistent application data (DATA mounts). This is what gets backed up.

The files/ directory contains config files copied from the app definition (FILE mounts). These are regenerated on install/upgrade, not backed up.

Both mounts/ and files/ are within the deployment state directory, managed by the storage provider.