Plugs & sockets
Layer 6. Services. Services
Plugs and sockets are SHC’s declarative integration system: a mechanism for one deployment (“provider”) to expose a typed capability (a socket) that another deployment (“consumer”) can plug into (a plug), with SHC executing the wiring as a series of jobs.
flowchart TB subgraph provider["provider deployment: postgres"] socket["socket: postgres<br/>name, jobs, schema"] end subgraph consumer["consumer deployment: wordpress"] plug["plug: postgres<br/>socket, data"] end socket --- plug provider -->|"integration jobs"| row["IntegrationModel row in the database<br/>(the durable edge)"] consumer -->|"integration jobs"| rowThe integration jobs run on connect and on backup. Disconnect runs none of them; see “Integration phases” below.
Source of truth (ce module):
modules/app/integration_service.go
(IntegrationService: connect/disconnect/auto-match),
modules/app/integration_render.go
(phase executor & template rendering),
modules/app/integration_magic.go
(CLI-spec parsing).
Where they’re defined
Section titled “Where they’re defined”Plugs and sockets live in separate YAML files inside the app
directory; they are not inlined into app.yaml:
| File pattern | Becomes |
|---|---|
*.socket.yaml | A socket definition (SocketDefinition) |
*.plug.yaml | A plug definition (PlugDefinition) |
*.vsocket.yaml | A vSocket (internal-only socket exposed by a vApp) |
*.vapp.yaml | A vApp (virtual app: a logical grouping a socket can represent) |
The filename stem (minus the .socket / .plug) becomes the default
name, so postgres.socket.yaml defines a socket named postgres.
For plugs, the default socket (which socket the plug wants to
connect to) is also derived from the filename unless overridden, so
an app with a postgres.plug.yaml will by default look for a socket
named postgres.
Loaded in AppDefinition.LoadSockets / LoadPlugs in
loader.go.
Naming a socket
Section titled “Naming a socket”The stem is not cosmetic: it is the contract’s identity. It selects a
schema, it resolves -i <plug>=<provider> (findSocketForPlug in
integration_render.go), it becomes the integrations.<stem>.* render
namespace, and every published registry archive plus every integration
row on every installed estate carries it. Renaming one later is a
migration, not an edit, so the name has to be right the first time.
The rule
Section titled “The rule”A socket is named for the wire protocol or contract it serves, never for the product that serves it, never for the outcome it achieves.
postgres, mysql, mongodb, redis, s3, smtp, imap, ipfs.
Every one of those names something two independent implementations can
both speak. None names a vendor; none names a goal.
This is already the estate’s practice, and the tells are everywhere:
- mailcow serves
smtp+imap, notmailcow. Themailapp directory runs mailpit and also servessmtp. - kubo serves
ipfs: the app is the reference implementation, the socket is the protocol it implements. - mariadb serves
mysql. Two unrelated products, one wire contract, one stem; a consumer’smysql.plug.yamlcannot tell which is on the other end. That indistinguishability is the feature. ce/modules/adapter/adapterplug.goenumerates the capability sockets and its header states the rule outright: “Capability sockets name the CAPABILITY, not the implementation (clean-break rename, §C7): oidc (was keycloak, then briefly the over-promisingsso; keycloak is the impl, any OIDC provider satisfies it), saml (its sibling), smtp + imap (split from mail) …”.oidcused to be calledkeycloak, thensso, andsmtp+imapused to be one socket calledmail. Every step was a clean break with no alias.
The test
Section titled “The test”Before naming a socket, answer both questions:
- Could a second, unrelated implementation serve this socket?
- Could an
external-<name>shim exist for it: an app that runs no service of its own and just publishes coordinates an operator pasted in?
If (1) is yes, you are naming a capability and the protocol name is
mandatory. Question (2) is question (1) made operational, and it is the
one that catches mistakes, because the shim has to be nameable:
external-postgres, external-mysql, external-mongodb,
external-redis, external-s3, external-smtp, external-imap,
external-gitlab all exist, and each serves a socket stem identical to
its own external- suffix. If you cannot write down what the shim would
be called, the socket name is wrong.
external-gitlab is the one worth reading before you write the next
shim, because it is where the pattern stops being free. The others front
a protocol whose credential an operator already holds. GitLab’s bundled
socket MINTS a fresh per-consumer token and revokes it on disconnect, and
the shim cannot: there is no container to run gitlab-rails runner in on
somebody else’s server. So the shim publishes ONE pasted token, shared by
every consumer bound to it, that SHC never rotates and never revokes. That
is a real downgrade, and the app says so in its own header rather than
letting the external- prefix imply parity. A shim is a way to reach an
instance you do not run, not a way to get the bundled provider’s
guarantees somewhere else.
The second class: singleton sockets
Section titled “The second class: singleton sockets”The rule above is not “protocol always wins”, and pretending otherwise would make most of the catalog look broken. There is a legitimate second class:
A socket for a capability only one app will ever provide is named
after that app. immich, metabase, blockscout, windmill,
penpot, sonarqube: the app is the capability, there is no wire
protocol to name because there is no second speaker, and inventing an
abstract name for a one-implementation contract buys nothing.
The estate therefore has two rules, and the test picks between them. The failure mode is not “wrong class of name”; it is answering the test wrong, and it goes wrong in both directions.
Worked example 1: sso, named by outcome (too abstract; renamed)
Section titled “Worked example 1: sso, named by outcome (too abstract; renamed)”“Single sign-on” is an outcome, not a wire contract. Outcomes have no
schema a second implementation can promise to honor: SSO is satisfied
by OIDC, by SAML, by an LDAP bind, and by header injection behind a
forward-auth proxy. Three of those are live in this estate today
(ce/modules/traefik is the forward-auth one); ldap is a declared
capability slot in adapterplug.go with no current catalog provider
(decision).
This estate ran an outcome-named sso socket long enough to measure the
damage, and the stem ended up carrying three unrelated contracts at
once:
- the OIDC face: 31 consumer plugs under
apps/, plusce/modules/{traefik,openobserve}, served by the keycloak addon andapps/standalone/external-oidc; - the SAML face: mautic, which read the socket’s
hostname/portto build…/realms/<realm>/protocol/saml/descriptor(a Keycloak SAML IdP descriptor, an endpoint no generic OIDC issuer has) and then put a SAML entityID inclientIdand a SAML ACS URL inredirectUris, while the socket minted the client asopenid-connect, so every login failed at the IdP after both jobs printed success; - the admin face:
adminUrl/adminUser/adminPassword, the Keycloak master-realm admin credential, not an authentication contract at all.
That breaks tier-1 substitutability, which is the whole promise of a
capability socket: plugged into external-oidc, mautic’s install went
green with login broken, because an outcome name gives the plug no
vocabulary to declare which face it needs. The clearest tell was the
Cloudron adapter, which mapped a foreign addon named literally oidc
onto the sso socket and then re-derived CLOUDRON_OIDC_*, every one
an OIDC-specific string synthesized inside a socket claiming not to be
OIDC-specific. The foreign platform used the protocol name; SHC
translated it into an outcome name and then paid to translate it back.
The fix landed as a clean-break split into protocol names: oidc
(served by ce/modules/keycloak and apps/standalone/external-oidc) and saml
(served by ce/modules/keycloak; consumed by mautic and sonarqube),
with the consumer plugs renamed to match. The decision record,
including why provisioning the wrong protocol reports success and fails
at first login, is
2026-08-05-oidc-and-saml-sockets.md.
The admin face is the remaining debt: adminUrl/adminUser/
adminPassword still ride the oidc socket’s schema, and its own
header flags them as provider-specific residue rather than contract.
Worked example 2: ivatar → libravatar, named by product (too concrete)
Section titled “Worked example 2: ivatar → libravatar, named by product (too concrete)”ivatar is one implementation of the libravatar federated-avatar
protocol. Under the product name the shim was literally inexpressible:
you cannot call it external-ivatar and point it at somebody else’s
libravatar server without claiming they run ivatar. Test question (2)
answered no under ivatar and yes under libravatar, so the socket
was renamed: apps/security/ivatar/libravatar.socket.yaml, consumed by
apps/devops/gitlab/libravatar.plug.yaml. The app directory keeps the product
name, which is correct: the directory names the implementation, the
socket names the contract.
Worked example 3: ipfs, named right
Section titled “Worked example 3: ipfs, named right”apps/standalone/kubo/ipfs.socket.yaml. Kubo is the reference IPFS implementation;
IPFS is the protocol. Both test questions answer yes: a second
implementation could serve it, and external-ipfs pointed at a hosted
gateway is a sentence that makes sense. Nothing in the socket’s schema
(apiUrl, gatewayUrl, clusterApiUrl) mentions kubo.
Not everything cross-cutting is a socket
Section titled “Not everything cross-cutting is a socket”Naming correctly is the second question; the first is whether the thing
should be a socket at all. Telemetry is the standing counter-example:
there is no otel socket, deliberately. One existed
(openobserve.socket.yaml, publishing store ports plus root basic-auth)
and was deleted, because a direct app→store pipe bypasses the fabric’s
scope-stamp, scrub, filter and scoped routing. The surviving mechanism,
-i otel=OTEL, is a render-time compose mutation with zero YAML on
either side. See telemetry
fabric before proposing an otel
socket; re-adding one reverts a documented breaking change.
Stems are jinja keys: no hyphens
Section titled “Stems are jinja keys: no hyphens”A socket or plug stem becomes a template key
(integrations.<stem>.socket.<field>), and a hyphen there parses as
subtraction, not as part of an identifier. Multi-word stems are
therefore camelCase, never kebab-case: matrixAppservice,
postgresMas, postgresTemporal. The catalog is
clean and arch-fitness.sh keeps it that way (below).
The catalog today
Section titled “The catalog today”Every socket in apps/, plus the ce/modules providers, as of this
writing. “Providers” lists every app serving that stem.
| Socket | Providers | Class |
|---|---|---|
postgres | external-postgres, ce/modules/postgres | protocol ✅ |
mysql | mysql, mariadb, external-mysql | protocol ✅ |
mongodb | mongodb, external-mongodb | protocol ✅ |
redis | redis, external-redis | protocol ✅ |
s3 | s3, external-s3 | protocol ✅ |
smtp | mail, mailcow, external-smtp | protocol ✅ |
imap | mailcow, external-imap | protocol ✅ |
llm | ollama, external-llm | protocol ✅ |
ipfs | kubo | protocol ✅ |
libravatar | ivatar | protocol ✅ |
matrixAppservice | matrix | protocol ✅ |
oidc | external-oidc, ce/modules/keycloak | protocol ✅ |
saml | ce/modules/keycloak | protocol ✅ |
oidc and saml are the two halves of the identity capability; the
outcome-named sso stem they replaced is worked example 1.
imap has its first catalog consumer in
apps/collaboration/nextcloud/imap.plug.yaml: Nextcloud Mail admin
provisioning in master-password mode, riding the mailcow-shaped face of
the socket (every master key | default('')-guarded, because
external-imap publishes none of them).
Singletons (25), each served by the same-named app, all compliant
under rule two: blockscout, clickhouse, crowdsec, ethereum,
fleet, highlight, hockeypuck, hyperswitch, immich, keygen,
mautic, metabase, monica, netbird, nginx, paperless,
peertube, penpot, pmm, postiz, pulp, sonarqube, supabase,
wazuh, windmill.
matrix is the one to read carefully before copying. The stem looks
protocol-named, but the contract is a notification bot (one shared
alerts bot posting into one room), not the Matrix client-server API. A
consumer that needs to act as other local users wants
matrixAppservice, which is genuinely protocol-shaped. The socket’s own
header says so; read it rather than inferring the contract from the
stem.
Two vApp-backed families sit alongside these and name the capability
rather than a protocol (database, bucket, cache, site, plugin
vSockets); see vApps.
Every external-* shim’s socket stem matches its own suffix. That
alignment is the naming rule reduced to a one-line mechanical fact
(external-oidc serving sso used to be the one mismatch), and it is
what the lint below watches.
The lint
Section titled “The lint”scripts/arch-fitness.sh check 22 (run by make lint) enforces the
mechanical half of this page, as two named checks:
socket-stem-hyphen(hard zero): no*.socket.yaml/*.plug.yaml/*.vsocket.yaml/*.vapp.yamlstem may contain a hyphen. A correctness invariant, not a style preference (jinja subtraction, preceding section); the tree is at zero. App directories may keep their hyphens:dependency-track,ciso-assistant,uptime-kumaare untouched, because only the stem becomes a template key.external-shim-socket-stem(ratchet, ceiling 0): anapps/external-<name>/app must serve<name>.socket.yaml. The ceiling was 1 whileexternal-oidcstill servedsso.socket.yaml; theoidc/samlsplit renamed it and the ceiling dropped to 0 in the same stroke.
The lint deliberately does not try to detect product-named sockets
in general. A stem-vs-app-directory grep would flag all 25 legitimate
singletons and mariadb’s correctly named mysql socket at the same
time. A check with that false-positive rate gets muted, and a muted
check is worse than none. The external-* alignment rule is the
substitutability test in the one place where the tree already states
the protocol name twice and the two spellings can be compared
mechanically.
Socket schema
Section titled “Socket schema”A socket exports typed data that plugs can read. Both sides (provider-side socket data, consumer-side plug data) are optionally validated against a schema.
# Schema: validates data on both sides of the edge.schema: plug: database@string!: Database name to create username@string: Dedicated username (if omitted, uses admin creds) password@secret: Password (required if username provided) extensions@json: Optional list of PostgreSQL extensions socket: hostname@string!: PostgreSQL hostname port@port!: PostgreSQL port database@string!: Database name username@string!: Username password@secret!: Password
# Data: the values the socket exposes to connected plugs.# Jinja-templated; resolved at integration time.data: hostname: "{{ environment }}.postgres.{{ stack }}" port: 5432 database: "{{ vars.postgres.database }}" username: "{{ vars.postgres.username }}" password: "{{ vars.postgres.password }}"
# Jobs: see "Integration phases" below.jobs: discovery: [...] integration: [...] post_deployment: [...] unintegration: [...] cleanup: [...]Schema syntax
Section titled “Schema syntax”Field names use an annotation suffix:
name@<type>[!]: <description>.
@string,@secret,@port,@json,@int,@bool, …: the type- trailing
!: required @secret: resolved as a vault reference (value never logged, never serialized in events)
local_only: true
Section titled “local_only: true”A socket with local_only: true refuses connections from deployments
running on other nodes (raises X400954XNDSCK). Used for sockets
that expose a unix socket path, a localhost port, or anything
else that isn’t mesh-accessible.
Plug schema
Section titled “Plug schema”data: database: "{{ vars.postgres.database }}" # vars.yaml: myapp username: "{{ vars.postgres.username }}" # vars.yaml: myapp password: "{{ vars.postgres.password }}" # vars.yaml: ref+vault://postgres_password?autogen
# `required: true`: install is rejected until this plug is connected.# `required: false` (default): install proceeds; app must tolerate absence.# `required: "expression"`: evaluated as a Jinja condition against vars.Name the database and role after the consuming app, from its own vars,
never from {{ stack }}. In plug data:, {{ stack }} is the consumer
deployment’s name on every edge, and {{ provider_stack }} is the provider
deployment’s name on an edge to a deployment (-i postgres=pg) and empty on
an edge to a connection (-i s3=@b2; ce modules/app/integration_render.go,
SHC-1736). A role must not follow the deployment’s name: a consumer deployed
as postgres would ask the socket for the server’s own superuser, whose
password create-database then resets (SHC-1451). ce next’s postgres socket
refuses a plug role that is a superuser or the socket’s admin before it
changes anything, but don’t lean on that. A second install of the same app
against the same server sets other names with --var postgres.database=
and --var postgres.username=, as the shipped multiplatform-keycloak
does.
A required plug that is not connected fails the install fast with
X400994PLGREQ (before anything is deployed), naming the plugs and the
-i remedy. The canonical conditional shape is
required: "{{ not vars.postgres.hostname }}": the plug is required
unless the operator pointed the app at an external server via
--var postgres.hostname=…. Replays that don’t restate -i (bare
update, clone, recover) satisfy the gate through the deployment’s
persisted integration edges.
The socket: field (which socket name to connect to) is defaulted
to the plug’s filename-stem, so postgres.plug.yaml implicitly has
socket: postgres. Override it only if the plug and socket names
differ.
An optional top-level providers: list names the provider apps the
plug accepts, by their app.yaml name::
# apps/flagship/frappe/mysql.plug.yaml: Frappe 15 needs MariaDB, and the# Percona `mysql` app serves the same socket.providers: - mariadbWithout it the plug takes any provider that serves its socket. With it,
-i mysql=<stack> naming a deployment of any other app is refused
before anything renders (X400742PLGACC, naming the accepted apps), the
store offers and installs only those apps for the plug, and the catalog
build refuses a name it doesn’t publish serving the plug’s socket. A
connection bind (-i mysql=@db) isn’t judged, since a connection names
no app.
An optional top-level services: list pins which consumer services
actually consume the integration:
# Only the mail relay dials the SMTP socket.services: - mailWhen set, ONLY those services are attached to the provider’s network.
Without a pin, every consumer service attaches (legacy behavior), and
compose publishes each attached service’s short name as a DNS alias on
the provider network, so a consumer that ships a service named like one
of the provider’s (nginx, redis, …) shadows it for the provider’s
own internal traffic (docker DNS round-robins the shared alias). Pin
the consuming service(s) whenever the consumer’s compose has generic
service names. A pinned name that matches no rendered service warns
X200983PLGSVC and is skipped.
Nothing binds a plug by itself
Section titled “Nothing binds a plug by itself”A plug is bound only when an install or update says so: -i <plug>=<provider> for a deployed provider, -i <plug>=@<connection>
for a connection, or the app’s own variables pointing at a service
directly (--var s3.endpoint=…). With none of those the app runs on
whatever its own templating does without the plug, usually local
storage. There is no autoBind: key, no --no-auto-bind flag and no
storage.autoBind.* config: the old flag is refused (X400808ABNGON)
and the old key is retired (X409073CFGRTD), both naming -i.
Binding a running app moves no data. It changes where NEW data goes and
leaves what is already written where it is, so the order for a running
deployment is quiesce, copy the data into the provider, then shc update <stack> -i <plug>=<provider>. shc doctor’s app.unbound-plugs
says, at info level, which deployment leaves a plug unbound while its
tenant has a provider for it, and names that command.
SHC’s own modules follow the same rule. shc init --modules-config '{"openobserve":{"integrate":{"s3":"@my-conn"}}}' binds the managed
openobserve’s s3 plug on its first install; without an integrate
entry it installs on its own storage.
Binding S3 directly to a connection
Section titled “Binding S3 directly to a connection”-i s3=@<connection> selects the capability the connection serves. An
aws connection mints s3-bucket: a per-app bucket and IAM credential,
with the minted bucket overriding the consumer’s vars.s3.bucket.
Connections of type s3 or cloudflare serve s3; the consumer keeps
its own bucket, including a value set with --var s3.bucket=<bucket>.
Grant the capability that type serves, even when the app and connection
belong to the same tenant.
An edge keeps the capability and owner it was first minted with. If the
connection behind its name changes type or owner, the update refuses with
X409923CONMID; unbind the plug and bind it again.
For a held S3 key on an endpoint without a scoped minter, the grant needs an explicit acknowledgement:
shc connection grant b2 --tenant master --capability s3 --grantee corp \ --boundary '{"unscoped":true}'shc install nextcloud -t corp -i s3=@b2 --var s3.bucket=nextcloudThe app gets the key the edge serves, minted or held. SHC writes it over
the accessKey and secretKey fields of the app’s s3 plug, so the
app’s catalogue defaults for s3.accessKey and s3.secretKey never
outrank it. A value you set with --var s3.accessKey=... still wins, and
an empty one does not count as set, nor does a value an app swap
carried forward. The key is never written to the deployment’s edge state
or manifest; like any credential an app takes, it is in the rendered
compose. An app author reads the key as
integrations.s3.plug.data.accessKey | default(integrations.s3.socket.accessKey),
with any var last. tests/unit/catalog refuses a template that reads the
key var first, and a render check binds every catalogue app with an s3
plug to a connection and fails if its default key comes out.
On Exoscale SOS and Backblaze B2, a grant whose boundary names buckets
mints a per-app key restricted to those buckets. An unscoped grant serves
the connection’s own key, so apps sharing it can read each other’s objects.
Hetzner Object Storage and R2 connected through --type s3 have no scoped
minter: isolation there means one connection and one bucket-scoped key per
app. A grant with a bucket boundary on such an endpoint refuses with
X403465HLDNOSCOPE; it never falls back to the held key. The cloudflare
connection type instead provisions scoped R2 credentials.
The direct edge skips external-s3’s bucket check at install; a missing
bucket shows up when the app starts. It adds no bucket whitelist beyond
the grant’s boundary and includes no bucket data in backups. Use the
external-s3 front when you need its discovery and bucket checks.
House rule: a pinned service MUST declare networks:
Section titled “House rule: a pinned service MUST declare networks:”Every service named in a services: pin has to declare a networks:
list in compose.yaml, normally just default:
mail: image: … networks: - defaultAttachServicesToNetwork replaces an absent networks: list with
the provider network alone (deliberate: it stops short-lived consumer
deployments from exhausting docker’s address pool). So pinning a service that
declares nothing lifts it off compose’s implicit default the moment
someone installs with -i <plug>=<stack>, and the failure is silent in
the worst way. The deployment deploys, the container runs, the health rollup
is green, and only the siblings that dial it by short name break. huly’s
mail shipped exactly that shape: account/transactor POST to
http://mail:8097, so every signup confirmation and invite would have
stopped posting on any smtp-integrated install.
Declaring the network makes the provider network add alongside it.
Any network works: apps built on the networks: [public] pattern are
already correct, because the attach appends to a list that is present.
shc validate warns on the shape; the catalog is clean.
vapp: names the vApp instances a plug materializes on
Section titled “vapp: names the vApp instances a plug materializes on”Some edges land on a surface that is itself a vApp
instance on the consumer’s own host: a Nextcloud plugin, a WordPress
plugin, a Frappe app. A plug declares those instances instead of
creating the surfaces by hand. The canonical form is a list; a
single mapping is sugar for a one-element list (the shipped
apps/collaboration/nextcloud/imap.plug.yaml uses the single-map
spelling):
# single-map sugar: the nextcloud/imap casevapp: name: plugin # which vApp on the consumer app addon: mail # add-on for the instance instance: mail # instance name (installs as <stack>/mail) mode: create # require (default) | create
# list form: a frappe-flavored HR edge whose second app needs the firstvapp: - name: plugin addon: erpnext mode: create - name: plugin addon: hrms # hrms will not install before erpnext is on the bench mode: create - name: plugin addon: calendar mode: create when: "{{ vars.calendar.enabled }}" # optional; falsy = entry absentmode: require(the default): the edge expects the instance to already exist; the plug’s jobs gate on it and tell the operator theshc install <app>/<vapp>command when it is absent.mode: create: the engine materializes the instance after the consumer deploys, through the real vdeployment path (the same pathshc install nextcloud/mail -s <stack>takes), so it is visible inshc ls, quota-charged, and retained on detach: disconnecting the edge never uninstalls the instance or the user data behind it.version:: the add-on version pin, also spelled inline asaddon: name@version(the same@the install token carries; authoring both refuses as malformed, X400903INVAPP, as does aversion:with noaddon:to pin). A pinned entry materializes exactly that add-on version, at first materialization AND at every re-materialization, instead of riding the add-on’sdefault:as the catalogue moves it; unset keeps the existing resolution ladder, the add-on’s own default. A pin the add-on cannot serve refuses the materialization loudly (X404022ADNPIN on the X500933VAPMAT channel, before quota is charged or a gate row claimed) and never falls back to the default. And a pin never churns a converged instance: existence is matched by name, so a moved pin takes effect at the next materialization only; re-pinning a live instance stays the operator’s explicitshc install <app>/<name>@<version> -s <stack>, the same command the require-mode refusal prints (the printed fix carries the pin).when:: an optional condition gating whether the entry participates at all, inrequired:’s exact truthiness grammar: a YAML boolean taken as-is, or a Jinja condition string (bare or{{ }}-wrapped) evaluated against{vars, stack, environment, tenant}(the bare literalstrue/yes/onandfalse/no/off/none/nullshort-circuit without touching the expression evaluator). Any other YAML type refuses as malformed (X400903INVAPP). Unset means always active. Falsy makes the entry absent for both halves: the require gate does not refuse on it and the create half does not materialize it. Teardown reporting ignoreswhen:entirely: it reports what exists on disk, so an instance a condition once created is still real (and still retained on detach) even after the condition turns false; removal stays the operator’s explicitshc uninstall <stack>/<instance>.
List semantics: declaration order is the dependency order; there is no graph and no solver, the author writes the list in install order:
- Entries process strictly in sequence. The create half stops a plug’s list at its first failure (a later entry may assume the earlier one); every skipped entry is reported by name, and the idempotent converge on the next stated deploy resumes where the stop left off.
- A require-mode refusal names every missing instance at once: the joined fix is a single runnable shell line, never fix-one-rerun-discover-the-next.
- Two entries binding the same instance name refuse as malformed, and entries may mix modes freely (each carries its own).
A vApp alone is the default; a plug enters only where two deployments
meet. Nextcloud Office is shc install nextcloud/richdocuments
and nothing else: the store app ships a built-in CODE server, so
there is no edge to wire. Talk is shc install nextcloud/talk, complete for
peer-to-peer calls. The plug-with-vapp: shape applies only if the
backing server ever becomes its own top-level app (a Collabora
app speaking WOPI, or Talk’s High-Performance Backend
(signaling + TURN) for large rooms), because then there is a
cross-deployment edge for a plug to carry, and that plug would declare its
store app the way imap declares mail. Deferred by ruling
(2026-08-08): neither server ships as an app, and installing the add-ons
alone covers the actual need. Do not add office/talk sockets
before the separate deployments exist.
The plug-mechanism bake rule (owner, 2026-08-08), which scopes this
key: on a parent that supports BAKED apps (frappe: no upstream
marketplace, and a live gunicorn cannot import a runtime-added Python
app), a plug’s mechanism extension is IMAGE-OWNED: baked into the image
and activated through vars (activateApps / the plug’s own job), never
declared as a vapp: dependency. Frappe’s plugs therefore carry NO
vapp: keys; frappe/plugin vdeployments remain the path for
user-facing apps, which is exactly the set no plug needs. Parents
without a bake model (nextcloud: store apps are runtime volume content,
PHP has no preload window, occ-install is reliable) keep using vapp:
for the surfaces their edges land on; the nextcloud/imap → mail
declaration is the reference.
The key encodes a doctrine line: a plug never installs a top-level
app. A store app that is the mechanism of an edge may be installed
by a plug job: nextcloud’s user_oidc (oidc.plug.yaml) and
integration_openai (llm.plug.yaml) are the precedent: invisible
plumbing whose entire configuration is the credential the edge carries.
User-facing functionality is a vApp instance, declared via vapp:,
visible, quota-charged. apps/collaboration/nextcloud/imap.plug.yaml
is the reference shape: the Mail app is the plugin vApp’s mail
add-on, and the plug’s own jobs only reconcile admin provisioning
config against it, and delete that config again on detach, leaving
the instance standing.
The key landed in ce with three codes: X400969VAPREQ (require
refused: the declared instance is absent), X500933VAPMAT (create
materialization failed: loud, non-fatal), X200921VAPKEP (retention
notice on detach). The catalog’s pinned engine may predate them; on
such an engine vapp: parses as an ignored unknown key (plug files
are open maps), so a plug that declares mode: create must still
soft-gate in its jobs (check for the surface, name the install
command, exit 0), and the edge converges once the pin catches up.
How an integration is created
Section titled “How an integration is created”At install time
Section titled “At install time”The -i / --integration flag on shc install takes an integration
spec. Three forms are accepted (parsed by ParseIntegrationSpec in
integration_resolve.go):
| Form | Meaning |
|---|---|
<provider> | Auto-match this deployment’s plugs to the provider’s sockets. Works only if exactly one of the consumer’s plugs matches one of the provider’s sockets by name. |
<plug>=<provider> | Explicit plug name; socket name defaults from the plug’s socket: field. |
<plug>=<provider>.<socket> | Fully explicit. Required when the provider has multiple sockets with the same “type” and the plug’s default doesn’t uniquely identify one. |
# Auto-match: wordpress.plug.yaml's `postgres` plug → postgres deployment's `postgres` socketshc install wordpress --stack blog -i db-main
# Explicit plug, default socketshc install wordpress --stack blog -i postgres=db-main
# Fully explicitshc install wordpress --stack blog -i postgres=db-main.postgresAuto-match fails if:
- the provider has no sockets (
X400903INVAPP) - no plug matches any provider socket by name
- more than one plug matches (requires explicit syntax)
shc integration create|delete|list lets you manage integrations on
a running deployment (commands under modules/app/commands/integration.go).
The same phase pipeline runs.
The IntegrationModel row
Section titled “The IntegrationModel row”Every live integration is one row in the integration table keyed
by (tenant_name, consumer_deployment_id, consumer_plug_name), so a
plug has at most one active binding at a time. Connecting again
upserts the existing row in place; it does not first run the old
binding’s unintegration teardown. Repointing a plug
(shc update <stack> -i oidc=authentik over an existing oidc=keycloak)
therefore leaves the previous provider’s grant behind; only an explicit
disconnect (-i oidc!) or an uninstall runs the teardown. See
“Integration phases”.
Drawing the graph
Section titled “Drawing the graph”shc integration graph prints a scope’s deployments and the bindings
between them as one Graphviz DOT graph, so dot draws it:
shc integration graph -t corp | dot -Tjpg -o corp.jpgshc integration graph -t corp -s nextcloud | dot -Tsvg -o nextcloud.svgEach deployment is a box holding its services, with an arrow from a
service to each one its compose depends_on names. Each binding is an
arrow from the consumer to its provider, labelled with the plug: a
deployment, a connection (@aws-primary) or a system socket (OTEL). A
binding not connected yet is dashed, and one that failed is dashed red.
-t and -e narrow the way they do for shc ls: a tenant you don’t name
is every tenant you may read. -s draws one deployment with what it binds
to and what binds to it. The graph comes from the integration table and
each deployment’s stored spec, never from the runtime, so a docker, podman
and incus estate draw the same graph. A deployment installed before the
spec recorded depends_on shows its services without arrows between them
until its next update. -o json and -o yaml print the same graph as
data.
Integration phases
Section titled “Integration phases”Both socket and plug can declare jobs for four phases. On
connect(), SHC runs phases 1–3 in this fixed order; phase 4 runs on
teardown:
| Phase | Runs on | When |
|---|---|---|
1. discovery | provider | Probe the provider’s readiness and the socket’s credentials before integrating. Fails the install loudly; see below. |
2. integration | provider | Do the provisioning work: create databases, users, grants, API keys. Output of these jobs can be captured into the live integration data (see below). |
3. post_deployment | consumer | After the consumer is running and the compose network is joined; wire up last-mile state that requires a live consumer. |
4. unintegration | either | Tear down what the bind built: delete the OIDC client, revoke the bucket user, drop the bouncer key. Runs on shc uninstall (every edge) and on shc update <stack> -i <plug>! (the dropped edge only). WITHIN one edge the consumer’s plug jobs run first, then the provider’s socket jobs, so the consumer stops using a credential before the provider deletes it. |
Source: runSocketIntegrationJobs in
modules/app/socket_jobs.go (phases 1–2, on every
consumer install/update that exercises the socket),
runConsumerPlugPostDeploymentJobs in
modules/app/plug_jobs.go (phase 3), and
RunUnintegrationJobs in modules/app/unintegration_runner.go
(phase 4, wired into ExecuteComposeDown for the uninstall and via
modules/app/unintegration_disconnect.go for the disconnect).
cleanupis not a plug/socket phase. It is the vApp surface’s teardown phase, declared on*.vsocket.yamland run by the vApp cleanup runner; no*.plug.yamlor*.socket.yamlin either catalogue declares it, and nothing reads it there. It was also the pre-rename spelling ofunintegrationon this surface, and the rename was a clean break with no alias: ajobs.cleanup:block in a plug or socket file today parses, lists, and never runs. Spell itunintegration. (apps/security/crowdsec/tests/tests.batsguards exactly this for the wazuh plug.)
What teardown replays, and what it re-renders. A teardown job does not re-render its edge from scratch: that would read post-drift vars and revoke the wrong resource successfully. Each edge freezes its bind-time plug context into
edge_statesin the deployment’sstate.json, and teardown replays it: identifiers (bucket, database, realm, clientId) come back frozen, while@secretfields are re-rendered from the raw template the record stored, against the deployment’s current vars: a rotated credential has to authenticate at teardown, and a replayed one will not. The provider’s own socket data is re-rendered live and never persisted. An edge with no bind-time record (a deployment that predatesedge_states, or state lost to a partial restore) renders from the deployed app tree, and its jobs seeintegration.protectedas true, so a well-written destroy keeps the data.
Whether teardown destroys data is written in your socket’s job. SHC keeps no edge lifetime and no destroy gate. A teardown job that only releases access (revoke a client, remove a minted user) runs on every teardown. A job that destroys what the integration provisioned (empty a bucket, drop a database, uninstall an app with its tables) must decide for itself, from two inputs:
- a variable of the integration, declared in your socket’s
schema.plug(cleanup@booleanon the s3 sockets and on frappe) and read asintegration.plug.data.cleanup. Destroy only on a genuine true; every other spelling, a missing value included, keeps the data.integration.protected, which SHC renders into every teardown job. It is true when the consumer deployment is protected (shc protect), when its protection could not be read, or when the edge has no bind-time record. Destroy only when it is a genuine false.Check both before the job opens anything, so the retain path never authenticates, and keep the destroy in its own job beside the release so a retained resource never keeps its credential alive. The s3 sockets’
delete-bucket(apps/standalone/s3/s3.socket.yaml) is the reference shape, andtests/unit/catalog/unintegration_destroy_gate_test.golists every such job with the variable that arms it. A job that still declares the gonelifetime:key is refused (X400074UNILFT) rather than run.
A failing teardown job never fails the teardown. It is reported on the retained-cleanup channel (a coded warning line on
shc uninstall/shc update, plus aretainedframe on the daemon’s operation stream), because aborting would strand a deployment nobody can remove. A job this runner cannot execute faithfully (acontext: pipelinewithsteps:, a provider job withvolumes:) is refused LOUDLY as a leak (X500089UNISHP) rather than dispatched with the unsupported part silently dropped.
Still not torn down by a disconnect: a connection-backed (
-i s3=@aws-primary) edge’s minted sub-credential. That scoped IAM user is revoked on uninstall only, so-i s3=@aws-primary!leaves it behind.
Discovery probes
Section titled “Discovery probes”Every socket SHOULD ship a jobs.discovery probe as its first jobs
block. Discovery is tier-2 validation of the connection: it proves the
provider endpoint is reachable and the credentials the socket exposes
actually work, before any integration job depends on them. A failed
probe aborts the whole integration: a wrong password or dead endpoint
surfaces as a loud job failure naming the probe, never as a silently
broken consumer.
Three probe shapes are supported:
jobs: discovery: # container/service: same fields as an integration job, plus an # optional attempt budget. max_retries is the TOTAL number of # attempts; retry_interval the seconds between them. - name: check-postgres-ready context: container image: "{{ vars.images.postgres }}" command: pg_isready -h "$${PGHOST}" max_retries: 30 retry_interval: 3
# http: declarative GET probe, rewritten into a one-off curl # container attached to the provider's network (so in-cluster # hostnames resolve). `headers` values and `url` are templated # like every other job field; `insecure: true` maps to curl -k. - name: check-synapse-ready context: http url: "{{ integration.socket.data.internalHomeserverUrl }}/health" max_retries: 60 retry_interval: 3The probe should be cheap and idempotent (a health endpoint, a credentialed ping); it re-runs on every install/update that touches the integration.
Every discovery, integration and unintegration job takes a timeout: in
seconds, the budget of its command (each attempt, for a probe with
max_retries). It defaults to 600, and its clock starts when the command
does. Before the command, the node that runs a container job on incus or
apple places its image, makes the run’s project, creates the container and
starts it, and it gives that bring-up a bound of its own, the larger of
900 s and timeout. A command that runs past its timeout: fails with
X504075JOBTMO under the job’s name, ending with what the job printed; a
bring-up past its bound fails with X504319JOBUPT. On docker and podman a
container job is one compose run, so its timeout: also covers a cold
image pull. A job whose own script carries a deadline sets timeout:
above it, so the script’s diagnostic prints before the kill:
- name: check-postgres-ready context: container image: "{{ vars.images.postgres }}" command: ... # gives up after 600s and says why timeout: 720A socket job still running at the backstop described below, for a node
that stops answering, fails with X500124SKTTMO, which names the job,
the backstop, where its time went and the failure it stood at.
A plug’s post_deployment job takes the same timeout:, also 600 by
default, but its clock starts when the job’s command starts, not when
SHC dispatches it. Before the command, the node that runs the job gets
the consumer’s replica ready (provider names, the replica’s runner, its
mounts and networks, the exec start), and it allows itself 600 s for
that; running out fails the job before its command, naming the step it
was in.
A command that runs past its timeout: is cut with X500110JOBTMO,
which says where the time went, ends with the job’s output and names the
shc job status that holds the whole run.
The leader keeps one more bound, for a node that stops answering:
600 s, plus the bring-up bound, plus timeout, plus 60 s from dispatch.
At the default timeout that is 2,160 s, so one job on a wedged node can
hold an install or an update for about 36 minutes, and a job that sets
timeout: 900 (gitlab’s wait-for-gitlab-ready) for about 41. While it
waits:
- the consumer is already up and healthy, because
post_deploymentruns after it does, and a failed job never rolls it back; shc job history -t <tenant>lists the job’s run asrunningfrom its dispatch;- when the bound runs out, the job fails with
X500009INTJOBand the phases it reached, the install or update reports it as an integration job that did not complete, and the run’s row inshc job historykeeps the same record. Fix the node and runshc update <stack>again; the plug’s jobs run again with it.
A job field the runner does not read is refused at install and by
shc validate with X400361INTFLD, and so is an app.yaml top-level key
no reader looks for, with X400363APPKEY: a key that would parse and do
nothing fails loudly instead.
The phase job context
Section titled “The phase job context”Each job in an integration phase gets a richer context than a lifecycle-hook job:
{{ integration.socket.data.<key> }} → provider socket's data dict{{ integration.plug.data.<key> }} → consumer plug's data dict{{ stack }} / {{ stack_name }} → the deployment's stack name (the provider's for socket jobs, the consumer's for plug jobs){{ environment }} → the deployment environment{{ tenant }} → the consumer tenantstack, environment and tenant are top-level context
keys, not nested under integration.*. There is no
integration.socket.stack / integration.plug.stack /
integration.environment. A socket job’s {{ stack }} is the
provider deployment’s stack name, and a plug job’s {{ stack }} is the
consumer deployment’s stack name, as it is in the plug’s data:.
…plus whatever vars are available on whichever side (socket jobs
see provider vars; plug jobs see consumer vars). This is what lets
the shared create-database job in postgres.socket.yaml provision
any plug’s requested database without knowing the consumer in
advance.
Preparing a provider before the plug moves
Section titled “Preparing a provider before the plug moves”A data migration needs the destination before the restore and before the
edge moves: the role first, so pg_restore can give each table its owner,
then the database, with the source’s encoding and collation. A socket says
how in two more phases, which no connect runs:
| Phase | Runs on | When |
|---|---|---|
describe | the provider the plug is on | Report what the consumer holds there with ::shc-connection-value::KEY=VALUE:: lines. postgres reports encoding, lc_collate and lc_ctype. |
provision | the provider it is to move to | Make what the consumer needs, reading integration.source.data (what describe reported), integration.from and integration.consumer, and binding nothing. |
shc integration provision <deployment> -i <plug>=<provider> runs them
and prints what the provision jobs report. The postgres socket’s
provision job is its create-database, run inside the provider: it marks
the database and role it creates as the deployment’s
(COMMENT ... IS 'shc:<tenant>/<stack>/<environment>'), refuses a database
or role of that name it did not create, and a later
shc update <deployment> -i postgres=<provider> binds the marked database
as it stands. Both phases run in the provider (a service job, or a
container job for a provider outside the cluster), because a provider
admits a consumer’s job only once the deployment’s binding names it.
An edge that waits for its provider
Section titled “An edge that waits for its provider”Some providers can’t serve a consumer yet, and nothing is wrong. A fresh
Fizzy has no account until someone signs in, so grant-fizzy-token has
nowhere to put gitlab-fizzy’s bot. An integration job says so by printing
one line and exiting 0:
echo "::shc-waiting::fizzy's first account (the first sign-in to Fizzy creates it)::"The text between the markers is the condition, written for the operator. SHC then:
- stops that edge’s jobs there and goes on with the deploy. The deploy
prints
X200828INTWATnaming the edge and the condition; - skips the plug’s
post_deploymentjobs, which assume a finished edge; - keeps the binding pending.
shc integration lsshows it aswaiting, with the condition underwaiting for; - runs the edge’s
discoveryandintegrationjobs again from the edge watch of the node that holds the deployment, starting 15 seconds after the deploy and backing off to every 2 minutes. When a run no longer prints the marker, the binding readsconnectedand the plug’spost_deploymentjobs run. No second deploy is needed.
The edge is recorded in edge-waits.json beside the deployment’s
manifest. A redeploy rewrites it from what its own jobs said, and a
deployment that’s gone, or no longer binds the plug, stops waiting.
Wait only for something that will arrive by itself. A wrong account name or a bad credential is a failure and should exit non-zero, or the edge waits forever and says nothing new. The consumer must boot while the edge waits: gitlab-fizzy’s bridge answers its health check and retries Fizzy on a 401 until the grant lands. A path with nobody to retry the edge treats the marker as a failure.
Auto-injection into compose
Section titled “Auto-injection into compose”After integration jobs complete, SHC injects both sides of the edge into
the consumer’s compose rendering under integrations.<plug_name>: the
provider socket’s data dict at integrations.<plug_name>.socket.<key>
and the consumer plug’s own data at
integrations.<plug_name>.plug.data.<key>. Built by
BuildIntegrationsContext (integration_render.go); values a socket
integration job minted on stdout are folded into the socket half
afterwards by MergeJobMintedValues.
This is what makes the integration data visible to the consumer’s
compose.yaml:
services: app: environment: DATABASE_URL: "postgres://{{ integrations.postgres.plug.data.username }}:{{ integrations.postgres.plug.data.password }}@{{ integrations.postgres.socket.hostname }}:{{ integrations.postgres.socket.port }}/{{ integrations.postgres.plug.data.database }}"In practice every catalog app guards each read with a vars fallback so
the same compose renders unintegrated ({{ integrations.postgres.socket.hostname | default(vars.postgres.hostname) }}), because an unresolved key renders
as the empty string, not as an error.
Note: {{ integrations.<plug>.* }} (plural, keyed by plug name) in
the compose template, versus {{ integration.socket.data.* }} /
{{ integration.plug.data.* }} (singular, the in-flight integration)
inside a phase job.
vSockets and vApps
Section titled “vSockets and vApps”A vApp is a virtual app-level grouping that represents “the
consumer can talk to a postgres, whichever’s available,” without
hard-coding postgres as the provider. A vSocket is a socket
exposed by a vApp instead of a concrete deployment.
Practical effect: when a plug declares its socket as a vSocket, integration resolution looks across all deployments of a tenant for something that implements the vApp, not just for a deployment with that exact name.
See the vApps page for when to prefer vApps over direct socket names.
Uninstall ordering
Section titled “Uninstall ordering”During uninstall, ExecuteComposeDown walks every -i edge in the
deployment’s state.json sidecar and runs that edge’s unintegration
phase. (The integration table rows go with the deployment row, by
ON DELETE CASCADE; there is no per-edge row walk on this path.
../architecture/flows/uninstall.md still describes the Python flow
here and is stale on both points.)
The unintegration phase runs BEFORE the compose verb, immediately
after the pre_uninstall hooks, the last moment the consumer’s own
containers are up, which most of the catalogue’s plug jobs need (occ,
wp, gitea admin auth delete all exec into the consumer). It is
therefore also before the connection-credential revoke and before the
DNS release, so the provider is still reachable and any minted credential
a job authenticates with still exists.
So uninstall DOES revoke the OIDC client and drop the provisioned
resources the socket’s teardown names. Two things it still leaves: a
resource whose destroy job was not armed (see above; the job says so in
its output), and anything an integration job created that no
unintegration job undoes. A socket that provisions in phase 2 and
declares no phase 4 leaks by construction; the fix is authoring the
teardown, not a runner change.
Common questions
Section titled “Common questions”Why are plugs/sockets in separate files, not in app.yaml?
Section titled “Why are plugs/sockets in separate files, not in app.yaml?”Because they’re often copy-pasted across apps (every app that uses
Postgres can share the same postgres.plug.yaml). Keeping them as
separate files lets you vendor just the plug files you need into a
new app, and keeps app.yaml focused on the app’s own shape.
Should my app plug into a cache, or bundle its own?
Section titled “Should my app plug into a cache, or bundle its own?”Bundle its own. A cache (redis/valkey), a broker, and a derived search
index all belong in the app’s compose.yaml, with the volume excluded
from backup. A redis socket exists and is supported, but it is not the
default and no catalog app consumes it. Full rule, with the backup
consequence and the one documented exception (mailcow), in
bundled services.
Can one plug connect to multiple providers?
Section titled “Can one plug connect to multiple providers?”No. The unique key on IntegrationModel is
(tenant_name, consumer_deployment_id, consumer_plug_name): a plug
has at most one active binding. If you need to talk to two Postgres
instances, declare two plugs (postgresMain.plug.yaml,
postgresAnalytics.plug.yaml). Use camelCase for multi-instance plug
names: the filename stem becomes a template key
(integrations.postgresMain.socket.port), and a hyphen there parses as
subtraction, which is why the in-tree examples (matrix’s postgresMas,
postiz’s postgresTemporal) are camelCase.
Can a socket serve multiple consumers?
Section titled “Can a socket serve multiple consumers?”Yes. Sockets are one-to-many. The same postgres deployment’s
postgres socket can back a dozen consumer deployments. The socket’s
integration phase is run once per connecting plug, not once total.
What if a phase job fails?
Section titled “What if a phase job fails?”integration phase failure → connect() raises. The
IntegrationModel row is not created. The partial side-effects
(rows a job created in the provider’s DB, for example) are the app
author’s responsibility to make idempotent. A job that prints
::shc-waiting::<condition>:: and exits 0 hasn’t failed: see
An edge that waits for its provider.
unintegration phase failure → never fails the teardown. The uninstall
(or update) completes and the failure is reported as retained state
naming the job, the edge and the deployment (X500927UNILEK), so the
operator knows exactly what is still live and where. Make these jobs
idempotent and tolerant of an already-absent resource (the catalogue’s
own 2>/dev/null || true convention), because a completed teardown must
read as “nothing to do” on a re-run, not as a failure.
How do I debug a stuck integration?
Section titled “How do I debug a stuck integration?”shc integration list <stack> # what edges existshc job history -s <stack> # recent job runs including phase jobsshc logs -s <provider_stack_name> # look for DB errors etcRelated
Section titled “Related”- Integration doctrine: the rules this page implements: the direction test, bridge placement, and no cycles
- App definition: the
app.yamlschema - Bundled services: when not to reach for a plug
- Virtual apps (vApps / vSockets)
- Lifecycle hooks: the other job-running mechanism
- Architecture: app module:
IntegrationServiceand the phase executor internals - Flow: install: where integrations are created during install
- Flow: uninstall: where integrations are unwound
- CLI reference: app: integration management commands live under the app module