App development
Layer 6. Services. Services
How to write a service as an SHC app. Audience: app authors who want their service to install, upgrade, back up, and integrate cleanly.
For operating SHC itself, see ../guide/. For how the runtime
works under the hood, see ../architecture/.
Start here
Section titled “Start here”- The new line: new line, in development; every new-line feature in one table, one app that uses all of them, and the tutorial ladder
- Creating apps: walkthrough from zero to a deployable app
- shc.yaml: the recommended way to write an app’s services, SHC’s own strict schema, and
shc convertfor an app you have ascompose.yaml - App definition:
app.yamlschema: name, version, vars, category - App variables: the one layout of
vars.yaml, one object per backing service, the same field names, oneadminobject - What SHC does to your compose file: the import path, every compose key with what the render does to it
- x-shc directives: every
x-shc-*key, the ones an app writes and the ones SHC writes itself, with what the render does with each - Health probes: a healthcheck the runtime runs inside the container, or an
SHC-HTTPorSHC-TCPprobe the node runs from outside it, for an image with no shell, curl or wget - The Docker socket: what a deployment that binds the Docker socket gets in place of the host’s, what that socket answers and refuses, and how the containers it creates are counted and cleaned up
- Groups: run a database or a quorum as numbered members with the
{% members %}block, worked on a three-member replica set - Database apps, HA by scale: every catalogue database goes from one plain server to the engine’s own HA and back with
--scalealone, engine by engine - Replicas and pods: how services form pods, scale as replica projects and reach each other
- App buckets: the closed list of directories under
apps/, what each means, and the rule that decides which one your app goes in - Source resolution: how SHC finds your app’s
compose.yaml
Composition
Section titled “Composition”- Integration doctrine: start here. The rules: which side is the plug, which is the socket, where a bridge lives, and why there are no cycles
- Plugs and sockets: declarative dependencies between apps
- Brokers: the runtime half, for when a fact is keyed on the user set and a deploy-clocked plug job cannot carry it
- Bundled services: when to ship a cache or datastore in your own compose instead of integrating, and what that means for backup
- VApps: Virtual Apps that extend other apps (e.g. Traefik’s ACME plugin)
- Add-ons: versioned variable bundles published by an app, one
<name>.addon.yamlper add-on (the install-time catalogue)
Presentation
Section titled “Presentation”- Storefront pages: what your app’s marketplace page can be, what
landing:andgallery:control, and why a hand-written flagship page is an SHC-engineer-only surface - App features and openness: the closed
features:vocabulary (what the APPLICATION supports), thelicense.opennessaxis, and how both differ from free-formtags:and from curator-applied badges - App capabilities: generated, every application’s declared capabilities against what its app actually wires, plus the gap list
Lifecycle
Section titled “Lifecycle”- Lifecycle hooks: pre/post install, upgrade, uninstall, backup, restore
- Credential reconciliation: make vault the source of truth for an app’s persisted credential so it can be rotated without lockout
Reference material
Section titled “Reference material”- App catalog: the marketplace is the browseable catalog (ruled 2026-08-14); on a cluster,
shc catalog ls/shc search - The resource model on next: how a service’s quota becomes limits and reservations, scope caps, disk and node capacity
- Architecture: app module: how SHC internalizes app definitions
- Architecture: stack module: how an app becomes a deployment. The stack name (
-s) is the app-identity axis; the environment is the other.
shc@docs:~$