Skip to main content

Nextcloud

@sntxrr/nextcloudv2026.10.14.1· MIT(was none)· 1mo agoBEHAVIORS
01README

Health, version drift, setup checks, app updates and compatibility, verified backups and occ maintenance for a self-hosted Nextcloud. sync reads status.php and, with a serverinfo token, storage and user statistics; drift compares the running version against stable GitHub releases and reports the patch target and the next major separately, because Nextcloud refuses to skip a major and the newest release is often not a legal target; setupchecks records the admin overview's warnings as data; talkBots flags a Nextcloud Talk bot that is not enabled, whose webhook delivery errors rose since the last reading (Talk drops a message whose delivery fails and never resets the count, so the rise is the signal, not the total), or that is expected and missing; apps lists app store updates and, given a targetVersion, which enabled store apps have no release for it. backup dumps MySQL/MariaDB and archives the web-root directories an upgrade changes onto the machine swamp runs on, then reads both back (dump completion line and table count, tar header checksums and gzip CRC) and renames a backup that fails .FAILED; the database password stays in the container's environment and never reaches a command line. maintenance, dbRepair, updateApps and backup change state and are dry runs unless apply=true; each apply path re-reads the state afterwards and fails if the change did not take. occ runs through docker exec, locally or on a host over SSH with BatchMode. Four behaviours shape the implementation. Nextcloud 34 enforces trusted_domains on status.php and answers HTTP 400/code 15 when probed by IP, and Deno's fetch silently drops a Host header override, so baseUrl must be a trusted name and the error is named rather than reported as a bare 400. occ setupchecks exits 1 whenever any check warns, so exit 1 with a JSON report is data, not failure. Prerelease tags are spelled inconsistently (rc2 and RC2 both exist), so any suffixed tag is excluded, not parsed. And updates.nextcloud.com answers an empty 200 both for nothing to offer and for a query it did not understand, so it is not used. A failure to measure is raised, never reported as healthy, current or no updates.

02Release Notes

Declare SPDX license (MIT) in manifest.

03Behaviors1
@sntxrr/nextcloud/instancev2026.09.30.1nextcloud_instance.ts

Global Arguments

ArgumentTypeDescription
baseUrlstringBase URL of the instance, e.g. https://cloud.example.com. Must be a name
serverinfoToken?stringOptional serverinfo token, sent as the `NC-Token` header. Set it on the
sshHost?stringHost to run `occ` on over SSH. Omit to run `docker exec` locally, on the
sshUser?stringSSH user. Omit to use the SSH client's own configuration for the host.
strictHostKeyChecking?enumSSH StrictHostKeyChecking. `yes` refuses an unknown host key, which is
knownHostsFile?stringOptional UserKnownHostsFile for SSH.
dockerBin?stringDocker CLI on the target. Give a full path where docker is not on the
container?stringName of the Nextcloud application container.
occUser?stringUser `occ` runs as inside the container. Must own config.php, or occ
githubRepo?stringGitHub `owner/repo` whose releases define what is current.
githubToken?stringOptional GitHub token, only to raise the API rate limit. Needs no scopes
imageRepository?stringImage the deployment pulls. Reported in `drift` so a bump can be
imageVariant?stringTag suffix the deployment uses, e.g. `apache` for `34.0.4-apache` or
verifyRegistry?stringRegistry that image existence is checked against. Must answer the
verifyRepository?stringRepository path within `verifyRegistry`. Docker Hub official images live
appStoreUrl?stringNextcloud app store, used by `apps` with a `targetVersion` to check
timeoutMs?numberAbort each HTTP call after this long.
occTimeoutMs?numberAbort a read-only `occ` command after this long. Commands that change
fn sync()
Read status.php, and serverinfo when a token is configured. An unreachable instance is recorded as unhealthy, not raised. Read-only.
fn drift(runningVersion?: string, pageSize?: number, verifyImage?: boolean)
Compare the running version against stable releases, reporting the patch target and the next major separately (Nextcloud cannot skip a major), and confirm each target image exists. Read-only.
ArgumentTypeDescription
runningVersion?stringVersion to compare. Omit to read it from status.php. Supply it
pageSize?numberRecent releases to examine. Nextcloud ships three supported majors
verifyImage?booleanConfirm each offered target tag exists in the registry.
fn setupchecks()
Run occ setupchecks and record every check, with warnings and errors pulled out. Read-only.
fn talkBots(expectedBots?: array)
Read Nextcloud Talk's bots and flag a watched bot that is not enabled, one whose delivery errors rose since the last reading, or an expected bot that is missing. Talk drops a message whose webhook delivery fails and never resets the error count, so a rise is the signal. Read-only.
ArgumentTypeDescription
expectedBots?arrayBot names that must be installed and enabled. When given, only
fn apps(targetVersion?: string)
List installed apps and the ones with an app store update available. With targetVersion, also check every enabled store app has a stable release for that Nextcloud version. Read-only.
ArgumentTypeDescription
targetVersion?stringA Nextcloud version to check app compatibility against, usually
fn maintenance(mode: enum, apply?: boolean)
Turn maintenance mode on or off. Dry run unless apply=true; the apply path re-reads the mode and fails if it did not change.
ArgumentTypeDescription
modeenumThe state to put it in.
apply?booleanActually change the mode. Without it, report only.
fn dbRepair(apply?: boolean)
Find missing database indices, columns and primary keys, the repairs the admin overview asks for after an upgrade. Dry run unless apply=true; the apply path re-runs the dry run and fails if anything is still pending.
ArgumentTypeDescription
apply?booleanRun the repairs. Adding an index to a large table can take
fn updateApps(apps?: array, apply?: boolean)
Update apps from the app store, either the named ones or every app with an update. Dry run unless apply=true; the apply path re-reads the update list and fails if a planned app still reports one.
ArgumentTypeDescription
apps?arrayApp ids to update. Empty means every app with an update.
apply?booleanRun the updates. Without it, report the plan only.
fn backup(destDir: string, label?: string, dbContainer: string, dbName?: string, dbUser?: string, dbPasswordEnv?: string, webRoot?: string, paths?: array, apply?: boolean)
Dump the MySQL/MariaDB database and archive web-root directories (config and custom_apps by default) into a new directory on the machine swamp runs on, then read both back to verify them. Dry run unless apply=true. The rollback point for an upgrade.
ArgumentTypeDescription
destDirstringExisting absolute directory, on the machine swamp runs on, to
label?stringPrefix of the backup directory, which is <label>-<UTC timestamp>.
dbContainerstringName of the MySQL/MariaDB container.
dbName?string
dbUser?stringDatabase user to dump as. root sees routines and events; the
dbPasswordEnv?stringEnvironment variable, inside the database container, that holds
webRoot?stringThe web root inside the application container.
paths?arrayDirectories directly under webRoot to archive. The defaults are
apply?booleanWrite the backup. Without it, measure what would be backed up

Resources

instance(infinite)— status.php and, with a token, serverinfo statistics.
drift(infinite)— Running version against stable releases: patch target, next major, and image availability.
setupchecks(infinite)— The admin overview's setup checks, as data.
talkBots(infinite)— Nextcloud Talk bots: state, delivery errors and their rise since the last reading.
apps(infinite)— Installed apps and available app updates.
maintenance(infinite)— Maintenance mode before and after a change.
dbRepair(infinite)— Missing indices, columns and primary keys, and their repair.
appUpdate(infinite)— An app update run: what was planned and what took.
backup(infinite)— A database dump and web-root archive: where it is and how it was verified.
04Previous Versions3
2026.09.30.1

Modified 1 behaviors. updated labels

2026.09.25.1

Modified 1 behaviors. updated labels

2026.09.24.1
05Stats
A
100 / 100
Downloads
38
Archive size
52.7 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels