Skip to content
SHC Docs

Virtual apps (vApps)

Layer 6. Services. Services

A vApp is a sub-resource that lives inside another deployment rather than as a top-level deployment of its own. vApps let a parent app expose “per-tenant instances” of something it provides (a Keycloak realm, a Postgres database, a MariaDB database, a bucket on the provisioning s3 app) without each instance being a full deployment with its own compose file, networks, and volumes. The bucket vApp is declared in apps/standalone/s3/bucket.vapp.yaml.

Source of truth (ce module): modules/app/vdeployment_runner.go (the synchronous vapp install path and the *.vapp.yaml / *.vsocket.yaml / *.vplug.yaml / *.vvars.yaml file contract), with the closed key set for those documents in modules/app/vdocument_lint.go, the cleanup guard in modules/app/vapp_cleanup_lint.go and modules/app/vdeployment_cleanup_report.go.


Use a vApp when:

  • The resource is naturally owned by a parent deployment (a realm belongs to a Keycloak, a bucket belongs to a provisioning s3 deployment).
  • You want many instances of it on one parent: a dozen realms on one Keycloak deployment, a dozen databases on one Postgres.
  • It has no containers of its own; it’s configuration applied to containers the parent already runs.

Use a deployment when:

  • It has its own compose file and runs independently.
  • It could plausibly live on a different node from the thing it integrates with.

vApps do not start any containers. They exist as rows in the database plus jobs that configure state inside parent-deployment services.


vApps and their instances use slash notation throughout:

ConceptFormatExample
App name in the catalog<parent-app>/<vapp>keycloak/realm, postgres/database
Address (<stack>/<instance>)the host deployment’s stack name, then the instancemy-keycloak/test-realm, dbs/blog

The stack name’s left-hand side identifies the host deployment (must already be installed); the right-hand side names this specific instance.


Files shipped with the postgres app (apps/postgres/):

apps/postgres/
├── app.yaml
├── compose.yaml # the actual postgres service
├── postgres.socket.yaml # admin-level socket
│
├── database.vapp.yaml # ← THE vAPP: a sub-resource "database"
├── database.vsocket.yaml # ← per-instance socket consumers plug into
├── database.vplug.yaml # ← vPlug definition (how the vApp talks to postgres)
└── database.vvars.yaml # ← variables the vApp auto-generates
version: "1.0"
name: database
app: postgres
type: vapp
description: "PostgreSQL database with dedicated user"
vars:
database: Database name
username: Database username
password@secret: Database password

This declares that the postgres app offers a database sub-resource with those three variables. app: postgres identifies the parent. type: vapp is the discriminator.

database.vsocket.yaml: the per-instance socket

Section titled “database.vsocket.yaml: the per-instance socket”
schema:
plug:
database@string!: Database name to create
username@string!: Database username
password@secret!: Database password
extensions@json: Optional list of PostgreSQL extensions
socket:
hostname@string!: PostgreSQL hostname
port@port!: PostgreSQL port
admin_user@string!: Admin username
admin_password@secret!: Admin password
data:
hostname: "{{ environment }}.postgres.{{ stack }}"
port: 5432
admin_user: "{{ vars.postgres.username }}"
admin_password: "{{ vars.postgres.password }}"
jobs:
integration:
- name: vapp-create-database
context: service
service: postgres
command: |
# create DB + user inside the parent postgres container
...

A vSocket is almost identical to a regular socket, but it’s scoped per vApp instance: when wordpress plugs into a specific instance of postgres/database, it gets that instance’s database name and password, not the parent postgres admin credentials.

database.vvars.yaml: auto-generated variables

Section titled “database.vvars.yaml: auto-generated variables”
username: "!ref+autogen?length=16&charset=alphanum"
password: "!ref+autogen?length=32"
database: "{{ vapp_instance }}"

Auto-generated values ensure every instance gets unique credentials without the operator having to supply them.


Terminal window
# Parent deployment already installed:
shc install postgres --stack dbs
# Install vApp instances into it:
shc install postgres/database --into dbs --instance blog
shc install postgres/database --into dbs --instance analytics
shc install postgres/database --into dbs --instance wiki

postgres/database names a vApp in the postgres app. --into dbs --instance blog says “host deployment dbs, instance name blog”. The full deployment identifier becomes dbs/blog.

Install flow (InstallVdeployment in vdeployment_runner.go):

  1. Validates the parent deployment exists (X400005PARNOF if not).
  2. Validates the instance name is unique on that parent (X409003STKEXS on collision).
  3. Refuses any key in the four documents that no loader reads (X400341VDCUNK / X400342VDCSHP; see The document key set is closed).
  4. Loads the vApp definition and vars; merges auto-generated and user-supplied values, then enforces the @type! required markers (X400978VARREQ).
  5. Persists a vdeployment row keyed by (host_deployment_id, instance_name). A vApp instance gets no deployment row of its own.
  6. Runs the vSocket’s discovery phase jobs and re-renders the vPlug data: block against what they printed.
  7. Runs the vSocket’s integration phase jobs inside parent-deployment services to provision the resource (create the database, create the user, grant privileges).

vApps do not run compose up: all their work happens through jobs against services the parent deployment already runs.

vApp instances appear as regular deployments in the listings:

Terminal window
$ shc ls
NAME APP ENV STATUS
dbs postgres default running
dbs/blog postgres/database default running
dbs/analytics postgres/database default running
my-keycloak keycloak default running
my-keycloak/qa keycloak/realm default running

A vApp instance presents itself as a regular deployment. The consumer plugs into it the same way it would any other deployment, by stack name:

Terminal window
# WordPress's `postgres` plug connects to the `blog` instance
# of postgres on the `dbs` deployment:
shc install wordpress --stack blog \
-i postgres=dbs/blog

The <plugname>=<stack-name> form names the target deployment. Because vApp instances are deployments, the same syntax works: the consumer doesn’t need to know it’s connecting to a vApp rather than a top-level deployment. The consumer’s integrations.postgres.socket.* template context is populated from the vApp instance’s vSocket data, which contains per-instance credentials, not parent-deployment admin credentials.


OperationWhat happens
shc uninstall <parent>vApp instances are uninstalled first (unintegrated + cleaned up) before the parent’s compose-down
shc uninstall <parent>/<instance>Only that instance’s cleanup phase runs; parent untouched. An instance the parent does not hold refuses X404070VDPNOF and runs nothing
shc backup create <parent>vApp instance data is included in the parent’s backup
shc backup restore <parent>vApp instances are restored; the parent app’s own post_restore hook replays (a vSocket has no restore phase)
shc clone <parent>vApp instances are copied with the parent deployment; source instances remain
shc update <parent> --where '<key>=<value>' relocating itvApp instances move with the parent

vApp teardown is driven by UninstallVdeployment in vdeployment_runner.go. It replays the persisted plug context against jobs.cleanup, and it deliberately does not run the document key check, so a catalogue edit that lands a bad key under a live instance can never make that instance unremovable.


vApps vs plugs-and-sockets: when do I use which?

Section titled “vApps vs plugs-and-sockets: when do I use which?”
ScenarioUse
I want a blog to connect to an existing Postgres databasea plug on the blog, a socket on Postgres
I want the blog to get its own private database inside a shared Postgresa vApp instance of postgres/database, then a plug on the blog connecting to that instance’s deployment
I want each tenant of my multi-tenant app to get its own Keycloak realma vApp instance of keycloak/realm per tenant against a shared Keycloak
I want one Redis shared across 20 deploymentsa plain socket on Redis, plugs on each consumer

Rule of thumb: if the thing being provisioned has per-consumer state (a database, a realm, a bucket), use a vApp. If it’s a shared cache / shared service with no per-consumer state to create, use a plain socket.


  • shc search: shows both regular apps and vApps (vApp names contain a slash, e.g. keycloak/realm); pass a query to filter across both.
  • shc ls: lists installed deployments; vApp instances show as <parent>/<instance> with their parent’s app name as the app.
  • shc search --kind vapp: filters to vApp catalog entries only.

The catalog index (apps.json) lists vApps with a parent_app and type: vapp discriminator. vApps are auto-discovered from *.vapp.yaml files within app directories during repo sync.

A *.vapp.yaml may declare hidden: true, the same authoring key an app.yaml carries (see catalog visibility):

name: bucket
app: s3
type: vapp
hidden: true # a bucket is provisioned by an integration, never picked off a listing

On a vApp the key records the author’s verdict that this sub-resource is reached through an integration or an explicit name rather than offered as a choice; s3/bucket is the shipped example. It never makes the vApp uninstallable (naming it still installs it), and it never affects publication: the bucket vApp rides the s3 app into every repo. Keeping an app out of the registry is the separate private: key on app.yaml; see Publication.


vApps share endpoints with regular apps and deployments:

OperationEndpointNotes
List appsGET /api/resource/AppFilter vApps with ?vapp=true or ?parent_app=X
Get appGET /api/resource/App/{name}{name} may be keycloak/realm
InstallPOST /api/method/shc.stack.installPass the parent/instance pair via stack_name (slash-separated)
List deploymentsGET /api/resource/Stack?environment=XIncludes vApp instances; each carries parent_stack
UninstallDELETE /api/resource/Stack/{name}On a parent, cascades to child vApp instances

Schema-wise, AppModel carries parent_app (str?) and vapp (bool); an installed instance is a vdeployment row whose host_deployment_id names its host deployment, beside instance_name and vapp_name.


Minimal layout:

apps/myapp/
├── app.yaml
├── compose.yaml
├── myapp.socket.yaml # optional: admin-level socket
│
├── resource.vapp.yaml # the vApp definition
├── resource.vsocket.yaml # per-instance socket
└── resource.vvars.yaml # auto-generated per-instance vars

resource.vapp.yaml:

name: resource
app: myapp
type: vapp
version: "1.0"
description: A per-instance resource inside myapp
vars:
instance_name@string!: Name of the instance
credential@secret: Generated credential

resource.vsocket.yaml: like a regular *.socket.yaml, with jobs.integration calling context: service against services the parent app already runs. Prefer context: service over context: container with your own image: a vApp doesn’t own any containers, so a service-context job that execs into a parent service is the idiom.


Every one of the four documents is decoded into a partial Go struct. YAML happily accepts a key the struct does not name and then throws it away, so a key SHC does not read used to be indistinguishable on disk from one whose request was honoured. It no longer is: a key no loader reads refuses the install (X400341VDCUNK) and is reported by shc validate, and a value whose shape cannot be decoded refuses too (X400342VDCSHP).

This closed exactly the bug that motivated it. postgres/database shipped a jobs.post_deployment: phase (a whole job wiring its own extensions@json plug field), and nothing ever ran it, because post_deployment belongs to the consumer plug surface (<plug>.plug.yaml, run after the consumer’s compose-up) and a vDeployment starts no containers at all. Every instance ever created ignored its extensions var without a word.

DocumentKeys
<vapp>.vapp.yamlversion, name, app, type, description, hidden, vars
<vapp>.vsocket.yamlschema (plug, socket), data, jobs
<vapp>.vplug.yamlvsocket, data
addons/<name>.addon.yamlone add-on: vapp, name, description, icon, homepage, category, tags, hidden, default, versions, aliases, vars
<vapp>.vvars.yamlnot checked: its keys are the vApp’s variable names, declared in the .vapp.yaml vars: block

A vSocket has exactly three phases, and they are not the plug/socket surface’s phases:

PhaseWhen
jobs.discoveryfirst; each job’s stdout is parsed and exposed as {{ discovery.<job_name> }}, and the vPlug data: block is re-rendered against it
jobs.integrationprovisioning, in the order written, aborting on the first failure
jobs.cleanupon shc uninstall <parent>/<instance>, against the persisted plug context

There is no post_deployment and no unintegration here: those are the plug/socket surface’s, and writing one is refused with a message naming where it does belong.

Each job entry takes name, context, service, image, command, user, working_dir, environment and timeout (seconds; the module default is 600).


A plugin-shaped vApp (nextcloud/plugin, wordpress/plugin, frappe/plugin) usually ships a curated catalogue beside it: an addons/ directory whose files are the known-good plugins an operator installs by name. One file is one add-on: addons/<name>.addon.yaml, the stem being the name, and an add-on belongs to this vApp by declaring vapp: <vapp> (an add-on with no vapp: key configures the parent app instead). The mechanism is only a named var bundle with a version map; everything ecosystem-shaped about a good catalogue is authoring convention, and the convention is a contract (catalog.md §35.6), written down here because breaking it has already produced production bugs:

  1. Declare the vvars in the vApp, and every add-on var name must match a declared vvar exactly. Add-on vars are merged into the vvars map by name, and an undeclared key is silently dropped: no error, no report. This is not hypothetical: every entry in the nextcloud plugin catalogue once set app_id while the vApp declared appId, so the key was dropped, the vvars default (calendar) won, and shc install nextcloud/talk installed the Calendar app, as did every other entry in the catalogue. Green install, wrong software, no diagnostic anywhere.
  2. Per-item constants go in vars; per-version deltas go in the versions overlay. A value that never changes across versions (an app id, a slug, a repo url) belongs in vars; the overlay carries only what the version choice changes (a git ref, a pinned tag).
  3. Version keys mirror upstream’s own identifiers when upstream is selectable; a single latest key when it is not. The frappe catalogue keys entries by upstream git tags (v15.59.0, …) because bench get-app genuinely installs the ref you name. The nextcloud catalogue uses one latest key because occ app:install takes no version at all: a per-rung map there would be identical vars pretending to pin something.
  4. Name a default, and fill the display keys (description at minimum). The default is what an unversioned shc install <app>/<name> resolves; the display keys are literally what the catalogue renders on the tile. They are top-level keys of the add-on document; the old meta: sub-map is gone, because a file is one add-on and there is nothing left to disambiguate.

Rules 1 and 4 are enforced by the catalogue-wide unit gate (tests/unit/catalog/addon_var_parity_test.go) because both have already failed silently. What the unit gate deliberately does NOT check is whether a pinned upstream ref still exists: that needs the network and lives in the freshness guard (make catalog/freshness); see Add-ons: keeping a catalogue fresh.