Step 7: a vapp
New line, in development. Installed on a four-node test cluster built from shc next
b43f0c168(ce5db649eb) 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:
| File | What it says |
|---|---|
database.vapp.yaml | The vapp’s name, its parent app (postgres) and its variables: database, username, password, cleanup. |
database.vvars.yaml | Defaults: password: "ref+vault://vapp_db_password?autogen", cleanup: false. |
database.vplug.yaml | What an instance asks for: a database and a user both named after the instance. |
database.vsocket.yaml | What the parent offers and the vapp-create-database job it runs inside the parent’s postgres service. |
Install an instance
Section titled “Install an instance”$ shc install postgres/database --into pg --instance blog -t riginstalling stack "pg/blog"pg/blog: startinginstalled deployment "pg/blog"$ shc ls -t rigSTACK TENANT ENV APP STATUS NODEpg rig prod postgres running far01pg/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.
What it made
Section titled “What it made”$ 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|tA consumer connects to the instance by its stack name, -i postgres=pg/blog, the same way step 4 connected to pg (Virtual apps).
Remove it
Section titled “Remove it”$ shc uninstall pg/blog -t rig -yuninstalling 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'"blogThe 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.