Skip to content
SHC Docs

A vapp and an add-on

A vapp lives inside another deployment. It has no compose file and starts no container: installing one runs its jobs in the parent’s containers. The catalogue Postgres carries one, postgres/database. Give notes its own: a database and the user that owns it.

Four files make a vapp, all in the parent app’s directory. Create them on home01.

/usr/share/shc/apps/notes/database.vapp.yaml
version: "1.0"
name: database
app: notes
type: vapp
description: A database and the user that owns it
vars:
password@secret: the user's password
cleanup: drop the database and the user when the instance is removed
/usr/share/shc/apps/notes/database.vvars.yaml
password: P@ssw0rd
cleanup: false
/usr/share/shc/apps/notes/database.vplug.yaml
vsocket: database
data:
database: "{{ instance_name }}"
username: "{{ instance_name }}"
password: "{{ vars.password }}"
cleanup: "{{ vars.cleanup }}"
/usr/share/shc/apps/notes/database.vsocket.yaml
schema:
plug:
database@identifier!: the database to create
username@identifier!: the user that owns it
password@secret!: that user's password
cleanup@boolean: drop both when the instance is removed
socket:
hostname@string!: the host Postgres answers on
port@port!: the port it answers on
data:
hostname: "{{ environment }}.postgres.{{ stack }}"
port: 5432
jobs:
integration:
- name: create
context: service
service: postgres
environment:
DB: "{{ integration.plug.data.database }}"
OWNER: "{{ integration.plug.data.username }}"
PASSWORD: "{{ integration.plug.data.password }}"
command: |
psql -U postgres -v ON_ERROR_STOP=1 <<'SQL'
\getenv db DB
\getenv owner OWNER
\getenv password PASSWORD
create user :"owner" password :'password';
create database :"db" owner :"owner";
SQL
cleanup:
- name: drop
context: service
service: postgres
environment:
DB: "{{ integration.plug.data.database }}"
OWNER: "{{ integration.plug.data.username }}"
command: |
psql -U postgres -v ON_ERROR_STOP=1 <<'SQL'
\getenv db DB
\getenv owner OWNER
drop database :"db";
drop user :"owner";
SQL

database.vapp.yaml names the vapp, the app it belongs to and its variables. database.vvars.yaml gives them defaults. database.vplug.yaml is what an instance asks the parent for: a database and a user, both named after the instance. database.vsocket.yaml is what the parent does about it: its integration jobs run at install and its cleanup jobs at removal, inside the parent’s postgres service, and psql reads the plug’s values from the environment with \getenv. Its data is what an app whose plug connects to an instance gets back. See Virtual apps.

Install an instance named shop into placed. --into names the parent and --instance names the instance.

home01
$ shc install notes/database --into placed --instance shop
installing deployment "placed/shop"
✔ installed deployment "placed/shop"
$ shc exec -s placed -S postgres -- psql -U postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname = 'shop'"
shop|shop

An add-on is a set of variables published under a name, so an install can name a known configuration instead of typing --vars. This one belongs to the database vapp and turns cleanup on.

/usr/share/shc/apps/notes/addons/blog.addon.yaml
vapp: database
description: a database for a blog, dropped with its instance
vars:
cleanup: true

The file’s name is the add-on’s name, and vapp: database says which vapp it configures. See Add-ons.

home01
$ shc install notes/blog --into placed
installing deployment "placed/blog"
✔ installed deployment "placed/blog"
$ shc ls
STACK TENANT ENV APP STATUS NODE
cloud prod prod nextcloud running home01
db prod prod postgres running home01
pgweb prod prod /root/learn/pgweb running home01
placed prod prod notes running home01
store prod prod /root/learn/versitygw running home01
web prod prod /root/learn/nginx running home01
placed/shop prod prod notes/database running -
placed/blog prod prod notes/database running -
$ shc exec -s placed -S postgres -- psql -U postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname in ('shop', 'blog') order by 1"
blog|blog
shop|shop

The add-on named the instance after itself. Each instance is a row with no node, because it runs nothing. Remove both.

home01
$ shc uninstall placed/shop -y
uninstalling deployment "placed/shop"
[placed/shop] Complete 1/1
✔ tear down
✔ uninstalled deployment "placed/shop"
$ shc uninstall placed/blog -y
uninstalling deployment "placed/blog"
[placed/blog] Complete 1/1
✔ tear down
✔ uninstalled deployment "placed/blog"
$ shc exec -s placed -S postgres -- psql -U postgres -tAc "select datname from pg_database where datname in ('shop', 'blog') order by 1"
shop

SHC runs a vapp’s cleanup jobs only when the instance’s cleanup is true. shop took the default, false, so its database stays. blog took the add-on’s true, so its database is gone.

Read Underneath the vapp before going on; it reads what this page left running.

Every page so far ran on home01 alone. The next two need more machines: a group whose members sit in two locations, and a node that fails while the others carry on.

Next: Postgres members across locations.