Add-ons
An add-on is a set of an app’s variables with a name and versions, so a
person installs a known setup by name instead of typing each --var. Each is
one file, addons/<name>.addon.yaml in the app’s directory; the file’s name
is the add-on’s. An add-on with no vapp key configures the app itself.
Give guestbook one for parties on home01.
title: Partydescription: guestbook set up for one event, open to many signershomepage: https://example.com/guestbook/partycategory: demotags: [event, open]default: "2026"vars: open: trueversions: "2026": greeting: Sign the party guestbook. maxSigners: 500 "2025": greeting: Sign last year's party guestbook. maxSigners: 200aliases: current: "2026"vars hold for every version, and each version adds its own. Every name must
be a variable guestbook declares: an unknown one would be dropped without a
word, so the catalogue’s tests refuse it. default is the version an install
gets when it names none. title, description, homepage, category and
tags are what a catalogue shows.
shc addon reads an app’s add-ons; --app-dir points it at a directory.
$ shc addon...$ shc addon ls guestbook --app-dir ~/learn/guestbook...$ shc addon versions guestbook/party --app-dir ~/learn/guestbook...$ shc addon show guestbook/party --app-dir ~/learn/guestbook...$ shc addon show guestbook/party@2025 --app-dir ~/learn/guestbook...show prints the variables a version resolves to. To install the add-on by
name, guestbook has to be in a catalogue with it. Pack guestbook as it is now,
1.3.0, into the shelf from Your own catalogue, and point the
index at it.
$ tar -czf ~/learn/shelf/files/guestbook-1.3.0.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 addonsapi_version: v2apps: - 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.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$ shc update shelf...$ shc repo sync mine...The catalogue shows the app with an add-on applied before anything is
installed. --addon names the add-on and --into the deployment it would
become; catalog compile prints just the install line, --addon-version
picks one of the add-on’s versions, and --integrate passes a plug=target
through to that line as written.
$ shc show guestbook --addon party --into party...$ shc catalog show guestbook --addon party --into party...$ shc catalog compile guestbook --addon party --addon-version 2025 --into lastparty --integrate counter=guestbook...An add-on is installed by its app and its name, one token. An app-level
add-on is a deployment of the app, with the add-on’s variables. guestbook
reads its API key from the vault, so the new deployment needs one too.
--into names the deployment the add-on becomes.
$ shc vault set api_key -s party --value-file ~/learn/api-key.txt...$ shc install guestbook/party --into party --expose party.learn.test...$ curl -sk --resolve party.learn.test:443:127.0.0.1 https://party.learn.test/greetingSign the party guestbook.@<version> picks another version, and an alias stands for the version it
names.
$ shc vault set api_key -s lastparty --value-file ~/learn/api-key.txt...$ shc install guestbook/party@2025 --into lastparty --expose lastparty.learn.test...$ curl -sk --resolve lastparty.learn.test:443:127.0.0.1 https://lastparty.learn.test/greetingSign last year's party guestbook.$ shc uninstall lastparty --yes...An add-on with vapp configures one of an app’s vApps instead, and installs
as an instance inside a running deployment of the app.
The app ladder’s A vapp and an add-on installs one; the
next page writes a vApp of your own and puts its instances in party, a deployment of the
catalogue’s guestbook. Keep party installed.
Next: Your own vApp.