Skip to content
SHC Docs

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.

~/learn/guestbook/addons/party.addon.yaml
title: Party
description: guestbook set up for one event, open to many signers
homepage: https://example.com/guestbook/party
category: demo
tags: [event, open]
default: "2026"
vars:
open: true
versions:
"2026":
greeting: Sign the party guestbook.
maxSigners: 500
"2025":
greeting: Sign last year's party guestbook.
maxSigners: 200
aliases:
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.

home01
$ 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.

home01
$ 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 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.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
...

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.

home01
$ 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.

home01
$ shc vault set api_key -s party --value-file ~/learn/api-key.txt
...
$ shc install guestbook/party --into party --expose party.learn.test
...
home01
$ curl -sk --resolve party.learn.test:443:127.0.0.1 https://party.learn.test/greeting
Sign the party guestbook.

@<version> picks another version, and an alias stands for the version it names.

home01
$ shc vault set api_key -s lastparty --value-file ~/learn/api-key.txt
...
$ shc install guestbook/party@2025 --into lastparty --expose lastparty.learn.test
...
home01
$ curl -sk --resolve lastparty.learn.test:443:127.0.0.1 https://lastparty.learn.test/greeting
Sign last year's party guestbook.
home01
$ 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.