Skip to content
SHC Docs

Step 6: Nextcloud add-ons

New line, in development. Installed on a four-node test cluster built from shc next b43f0c168 (ce 5db649eb) 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.

Calendar’s whole file, addons/calendar.addon.yaml:

vapp: plugin
title: "Calendar"
description: "CalDAV-based calendar management"
homepage: https://apps.nextcloud.com/apps/calendar
category: collaboration
tags: [caldav, productivity]
default: latest
versions:
latest:
appId: calendar
  • vapp: plugin says 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).
  • versions maps 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).

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:

Terminal window
$ shc search calendar -t rig
APPLICATION KIND VERSION REPO CATEGORY REQUIRES HIDDEN PARENT DESCRIPTION
nextcloud/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 form
nextcloud/plugin:calendar vaddon 34 rig collaboration a nextcloud deployment; values for its required vars false nextcloud/plugin CalDAV-based calendar management

shc 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.

Terminal window
$ shc install nextcloud/calendar --into cloud -t rig
installing stack "cloud/calendar"
cloud/calendar: starting
installed deployment "cloud/calendar"
$ shc install nextcloud/contacts --into cloud -t rig
installing stack "cloud/contacts"
cloud/contacts: starting
installed deployment "cloud/contacts"
$ shc ls -t rig
STACK TENANT ENV APP STATUS NODE
cloud rig prod nextcloud running far01
pg rig prod postgres running far01
cloud/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.

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:

Terminal window
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:

Terminal window
$ shc exec -s cloud -t rig -S nextcloud -u www-data -- php occ app:list

Both 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.

Terminal window
$ shc uninstall cloud/contacts -t rig -y
uninstalling stack "cloud/contacts"
cloud/contacts: tearing down stack "cloud/contacts"
uninstalled deployment "cloud/contacts"
cloud/contacts: removed with the deployment: config lanEnforcement

The 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.