Step 6: Nextcloud add-ons
New line, in development. Installed on a four-node test cluster built from shc next
b43f0c168(ce5db649eb) on 2026-10-08, on step 5’s Nextcloud. The output below is that run’s, trimmed.
An add-on is a named bundle of variables that an app package ships, so you install a known configuration by name instead of setting variables one at a time. Nextcloud ships 46 of them, one file each under apps/flagship/nextcloud/addons/. Each is a Nextcloud app from Nextcloud’s own store: Calendar, Contacts, Deck, Talk and so on.
Keep cloud from step 5 running.
What an add-on is made of
Section titled “What an add-on is made of”Calendar’s whole file, addons/calendar.addon.yaml:
vapp: plugintitle: "Calendar"description: "CalDAV-based calendar management"homepage: https://apps.nextcloud.com/apps/calendarcategory: collaborationtags: [caldav, productivity]default: latestversions: latest: appId: calendarvapp: pluginsays which vapp of the Nextcloud package the add-on installs into. A vapp is a resource inside a running deployment, with no containers of its own (step 7 builds one in Postgres).versionsmaps a version name to variables for that vapp. Here there is one,latest, and it sets one variable:appId: calendar.
The plugin vapp is four files in the Nextcloud package: plugin.vapp.yaml (its variables), plugin.vvars.yaml (their defaults), plugin.vplug.yaml (what an instance asks for) and plugin.vsocket.yaml (the jobs that do it).
See what the package ships
Section titled “See what the package ships”Nextcloud reached this cluster from a repository, so its add-ons are in the synced catalogue, one row each, named for the vapp they install into:
$ shc search calendar -t rigAPPLICATION KIND VERSION REPO CATEGORY REQUIRES HIDDEN PARENT DESCRIPTIONnextcloud/plugin:appointments vaddon 34 rig collaboration a nextcloud deployment; values for its required vars false nextcloud/plugin book appointments into your calendar through a secure online formnextcloud/plugin:calendar vaddon 34 rig collaboration a nextcloud deployment; values for its required vars false nextcloud/plugin CalDAV-based calendar managementshc catalog ls -t rig lists all of them. shc addon ls <app> and shc addon show <app>/<addon> read a package on this node’s disk instead: for an app a repository supplies they answer X404012APPDIR, and --app-dir <dir> points them at an unpacked copy.
Install two
Section titled “Install two”$ shc install nextcloud/calendar --into cloud -t riginstalling stack "cloud/calendar"cloud/calendar: startinginstalled deployment "cloud/calendar"$ shc install nextcloud/contacts --into cloud -t riginstalling stack "cloud/contacts"cloud/contacts: startinginstalled deployment "cloud/contacts"$ shc ls -t rigSTACK TENANT ENV APP STATUS NODEcloud rig prod nextcloud running far01pg rig prod postgres running far01cloud/calendar rig prod nextcloud/plugin running -cloud/contacts rig prod nextcloud/plugin running -nextcloud/calendar is one token: the app, then the add-on. There is no --addon flag, and you never type the vapp’s name, because the add-on’s file already says vapp: plugin. --into cloud names the parent deployment, which step 5 called cloud. With no --instance, each instance takes the add-on’s name, so these two are cloud/calendar and cloud/contacts: rows with no node, because they run nothing.
What SHC does
Section titled “What SHC does”No container starts and cloud’s compose file does not change. For each instance SHC runs the vsocket’s install-plugin job inside the running nextcloud service, as the www-data user:
php occ app:install "${APP_ID}" 2>/dev/null || php occ app:enable "${APP_ID}"occ app:install downloads the app from Nextcloud’s store and unpacks it into custom_apps/, so the Nextcloud container needs to reach apps.nextcloud.com. If the app is already there, the job enables it. The job refuses an appId that is not lower-case letters, digits and underscores, and it refuses an add-on marked unmaintained unless you pass --var acknowledged=true.
To check from the parent:
$ shc exec -s cloud -t rig -S nextcloud -u www-data -- php occ app:listBoth names were under Enabled in this run. -u www-data matters: occ refuses to run as any user but the one that owns Nextcloud’s files.
Remove one
Section titled “Remove one”$ shc uninstall cloud/contacts -t rig -yuninstalling stack "cloud/contacts"cloud/contacts: tearing down stack "cloud/contacts"uninstalled deployment "cloud/contacts"cloud/contacts: removed with the deployment: config lanEnforcementThe uninstall runs the vsocket’s uninstall-plugin job in the same service: php occ app:disable contacts, then php occ app:remove contacts. Calendar is untouched: after it, occ app:list had calendar under Enabled and no contacts.
Uninstall instances before their parent, as in step 7.
Next: Step 7: a vapp.