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 nextclouduses the app name unless--stacksets another. - Environment (
environment): the other axis. Unset folds todefault(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.
Environments
Section titled “Environments”Environment is an axis of the deployment. Common environment names:
| Environment | Purpose |
|---|---|
default | Default when not specified |
prod | Production workloads |
staging | Pre-production testing |
dev | Development and experimentation |
Environment-Specific Config
Section titled “Environment-Specific Config”# Override config for specific environmentshc config set backup.retention.daily 14 --scope stack -t acme -s myblogshc config set deploy.memory_quota 4g --scope deployment -t acme -s myblog -e prodEnvironment Isolation
Section titled “Environment Isolation”| Aspect | Shared Between Environments? |
|---|---|
| App definition | Yes (same app.yaml, compose.yaml) |
| Data volumes | No (each env has own mounts/ directory) |
| Config | Inherited but can be overridden per-env |
| Vault secrets | Can be scoped to environment or shared |
| Docker network | No (each env has own network) |
| Container names | No (each deployment has its own) |
Platform-Specific Paths
Section titled “Platform-Specific Paths”SHC uses a minimal set of directories, following XDG conventions on Linux:
Root Installation (System-Wide)
Section titled “Root Installation (System-Wide)”| Directory | Linux | macOS (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 |
User Installation (Per-User)
Section titled “User Installation (Per-User)”| Directory | All 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 |
Dev Mode
Section titled “Dev Mode”When running from source (go.mod detected), all paths consolidate under the project:
{project_root}/.shc/├── state/├── cache/├── run/└── logs/What’s NOT in paths.go
Section titled “What’s NOT in paths.go”- 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.
Directory Structure
Section titled “Directory Structure”Static Paths (paths.go)
Section titled “Static Paths (paths.go)”# 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 URLDeployment State
Section titled “Deployment State”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.jsonmanifest.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.
Database Modes (Mutually Exclusive)
Section titled “Database Modes (Mutually Exclusive)”| Mode | Database | Path |
|---|---|---|
| Single-node | SQLite (pure-Go, file + WAL) | {state_home}/shc.db |
| Cluster | rqlite (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.
Configuration
Section titled “Configuration”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
Section titled “Backups”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
Key File Locations
Section titled “Key File Locations”| File | Path | Purpose |
|---|---|---|
| SQLite DB | {state_home}/shc.db | Database (single-node) |
| rqlite dir | {state_home}/rqlite/ | Database (cluster) |
| Engine marker | {state_home}/engine.json | Cluster-engine flag |
| PID file | {runtime_dir}/shc.pid | Server process ID |
| Unix socket | {runtime_dir}/shc.sock | CLI-server communication |
| Global log | {logs_dir}/shc.log | System-wide log |
| Deployment log | {logs_dir}/tenants/.../shc.log | Per-deployment log |
| Git cache | {cache_home}/git/ | Cloned git repositories |
Mount Types
Section titled “Mount Types”| Type | Example | Location | Backed Up |
|---|---|---|---|
| DATA | pgdata:/var/lib/postgresql | mounts/pgdata/ | ✅ Yes |
| FILE | ./config.yaml:/app/config.yaml | files/config.yaml | ❌ No (part of app) |
| RUNTIME | tmp:/cache | /tmp/... | ❌ No (ephemeral) |
| SYSTEM | /var/run/docker.sock | unchanged | ❌ 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.
See Also
Section titled “See Also”- Deployment Identity
- File Locations
backupmodule: backup vs export, restore vs recover, archive formats- Overview