Skip to content
SHC Docs

Step 7: a vapp

New line, in development. Installed on a four-node test cluster built from shc next b43f0c168 (ce 5db649eb) on 2026-10-08. The output below is that run’s, trimmed.

A vapp is a resource that lives inside another deployment: a database in a Postgres, a realm in a Keycloak. It has no compose file and starts no containers. Installing one runs jobs in the parent’s services. The shipped Postgres has one, postgres/database. Keep pg from step 2 installed.

The vapp is four files in the Postgres package:

FileWhat it says
database.vapp.yamlThe vapp’s name, its parent app (postgres) and its variables: database, username, password, cleanup.
database.vvars.yamlDefaults: password: "ref+vault://vapp_db_password?autogen", cleanup: false.
database.vplug.yamlWhat an instance asks for: a database and a user both named after the instance.
database.vsocket.yamlWhat the parent offers and the vapp-create-database job it runs inside the parent’s postgres service.
Terminal window
$ shc install postgres/database --into pg --instance blog -t rig
installing stack "pg/blog"
pg/blog: starting
installed deployment "pg/blog"
$ shc ls -t rig
STACK TENANT ENV APP STATUS NODE
pg rig prod postgres running far01
pg/blog rig prod postgres/database running -

postgres/database names the vapp in the postgres app. --into pg names the parent deployment and --instance blog the instance, so the instance’s stack is pg/blog. The instance is a row in shc ls with no node, because it runs nothing.

Terminal window
$ shc exec -s pg -t rig -S postgres-1 -- psql -U postgres -d postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname = 'blog'"
blog|blog
$ shc exec -s pg -t rig -S postgres-1 -- psql -U postgres -d postgres -tAc "select rolname, rolcanlogin from pg_roles where rolname = 'blog'"
blog|t

A consumer connects to the instance by its stack name, -i postgres=pg/blog, the same way step 4 connected to pg (Virtual apps).

Terminal window
$ shc uninstall pg/blog -t rig -y
uninstalling stack "pg/blog"
pg/blog: tearing down stack "pg/blog"
uninstalled deployment "pg/blog"
pg/blog: removed with the deployment: config lanEnforcement
$ shc exec -s pg -t rig -S postgres-1 -- psql -U postgres -d postgres -tAc "select datname from pg_database where datname = 'blog'"
blog

The instance is gone and the database stays, because cleanup defaults to false. Install with --var cleanup=true to have the uninstall drop the database and its role.

Uninstall instances before their parent. Uninstalling pg does not uninstall pg/blog: it keeps the deployment’s vdeployments/ and mounts/ directories on its node for a reinstall (ce modules/app/install_runner.go, removeRenderedArtifacts).

That is the end of the ladder on next. To clean up, with every instance already removed: shc uninstall pg -t rig -y.