Skip to content
SHC Docs

Your own vApp

A vApp lives inside a deployment of its app. It has no compose file and runs no container: installing an instance runs jobs in the parent’s containers, and removing it runs others. Each instance is a row of its own in shc ls.

guestbook gets a board vApp: each board is a count of its own in the parent’s counter, started at a number the board chooses. Four files make it, all in guestbook’s directory on home01.

~/learn/guestbook/board.vapp.yaml
version: "1.0"
name: board
app: guestbook
type: vapp
description: A board inside a guestbook, with a count of its own
hidden: false
restartHost: true
vars:
start: the count a new board starts at
cleanup: delete the count when the board is removed
~/learn/guestbook/board.vvars.yaml
start: 0
cleanup: true
~/learn/guestbook/board.vplug.yaml
vsocket: board
data:
key: "board:{{ instance_name }}"
start: "{{ vars.start }}"
cleanup: "{{ vars.cleanup }}"
~/learn/guestbook/board.vsocket.yaml
schema:
plug:
key@string!: the counter key the board counts in
start@int: the count it starts at
cleanup@boolean: delete the count when the board is removed
socket:
hostname@string!: the counter's address
data:
hostname: "{{ environment }}.counter.{{ stack }}"
jobs:
integration:
- name: open
context: service
service: counter
command: redis-cli setnx {{ integration.plug.data.key }} {{ integration.plug.data.start }}
cleanup:
- name: close
context: service
service: counter
command: redis-cli del {{ integration.plug.data.key }}
  • board.vapp.yaml names the vApp, the app it belongs to and its variables. hidden: false keeps it on catalogue listings. restartHost: true restarts the parent deployment once an instance’s jobs have run, for an app that reads what they wrote only at start.
  • board.vvars.yaml gives the variables their defaults.
  • board.vplug.yaml is what an instance asks the parent for: a key named after the instance.
  • board.vsocket.yaml is what the parent does about it: integration at install and cleanup at removal, in the parent’s counter, and cleanup only for an instance whose cleanup is true.

An add-on for the vApp names a board setup: this one starts its count at a hundred and keeps it when the board goes.

~/learn/guestbook/addons/century.addon.yaml
vapp: board
title: Century
description: a board that starts at a hundred and keeps its count
default: latest
versions:
latest:
start: 100
cleanup: false

The vApp is part of the app, so it reaches the cluster in a new archive. Pack guestbook 1.3.1 and point the index at it.

home01
$ sed -i 's/^version: "1.3.0"/version: "1.3.1"/' ~/learn/guestbook/app.yaml
$ tar -czf ~/learn/shelf/files/guestbook-1.3.1.app -C ~/learn/guestbook app.yaml vars.yaml shc.yaml web.env icon.svg site seed.job.yaml count.job.yaml report.job.yaml ping-shelf.job.yaml counter.socket.yaml board.vapp.yaml board.vvars.yaml board.vplug.yaml board.vsocket.yaml addons
~/learn/shelf/files/index.yaml
api_version: v2
apps:
- name: guestbook
description: A page, an API under its path and a counter
category: demo
tags: [demo, redis, nginx]
homepage: https://example.com/guestbook
versions:
- version: "1.3.1"
archive: guestbook-1.3.1.app
- version: "1.3.0"
archive: guestbook-1.3.0.app
- version: "1.2.1"
archive: guestbook-1.2.1.app
- version: "1.2.0"
archive: guestbook-1.2.0.app
home01
$ shc update shelf
...
$ shc repo sync mine
...
$ shc search --kind vapp
...

A plug of guestbook can ask for a board when its edge connects. Its vapp block names the vApp, the add-on and the instance, and mode: create makes the instance after the consumer deploys and keeps it when the edge goes. This one points at keyfront’s store, which this ladder never installs, so the edge never connects; shc validate reads it.

~/learn/guestbook/store.plug.yaml
socket: store
required: false
services:
- web
vapp:
name: board
addon: century
instance: store
mode: create
home01
$ shc validate ~/learn/guestbook
...

An add-on of a vApp is read with --vapp, which names the vApp it belongs to. --instance names the instance a vApp would be installed as, beside --into for its parent.

home01
$ shc addon versions guestbook/century --vapp board --app-dir ~/learn/guestbook
...
$ shc addon show guestbook/century --vapp board --app-dir ~/learn/guestbook
...
$ shc show guestbook/board --into party --instance kids
...
$ shc catalog show guestbook/board --into party --instance kids
...
$ shc catalog compile guestbook/board --addon century --into party --instance kids
...

Install a board named kids into party. --into names the parent and --instance the board. The add-on is installed by its app and its name, and the instance takes the add-on’s name.

home01
$ shc install guestbook/board --into party --instance kids
...
$ shc install guestbook/century --into party
...
$ shc ls
...
$ shc exec -s party -S counter -- redis-cli mget board:kids board:century
0
100

Remove both. kids took the default cleanup, true, so its count goes; century took the add-on’s false, so its count stays.

home01
$ shc uninstall party/kids --yes
...
$ shc uninstall party/century --yes
...
$ shc exec -s party -S counter -- redis-cli exists board:kids board:century
1
$ shc uninstall party --yes
...

Next: Copies and deployfiles.