The webdav socket on nextcloud: the backup deposit edge
Status: open design. The provider half is built (2026-08-10) and paperless carries a
webdavplug. The owed list in this note is older than that work, so some of its items are done.apps/collaboration/nextcloud/webdav.socket.yamlnow exists: the §6 contract (hostname/origin/davPath/url/username/password/collection/quota), the §8.1 provision job (origin refusals, converge-on-exit-1 account, quota with read-back, not-admin assertion, PROPFIND-207 capability preflight) and the §8.1 report-only teardown, gated by validate-templates and a six-test guard block. Four deliberate deviations from the letter of §8.1, each keeping its spirit:data.passwordis| default('')-guarded (empty is the legal shim posture, and the provision job refuses an empty render with a named cause); the provision converges the account password withocc user:resetpasswordon the already-exists branch (otherwise a drifted vault value publishes a credential the preflight can only fail forever); the §10.1 home-materialisation unknown is handled in-job (occ files:scanwarm-up between two PROPFINDs, refusal naming the--groupfix if it survives); and the job asserts enabled + NOT-admin viauser:info --output=jsonbefore the preflight. Still owed: thevars.webdav.*blocks (§8.5) in the provider’s vars.yaml + app.yaml,webdav.plug.yamland the configure job on frappe (§8.2–8.3), thenextcloud_integrationbake (§8.4),external-webdav(§9.2), the frappe-side guards, and every §11 ruling. The upstream reads below remain measured; no archive has yet been deposited end to end.
What is measured (and it is most of this document) is the other end: the
upstream code the edge has to satisfy, read line by line off frappe
v15.117.0, off frappe/nextcloud-integration@main, and off the Nextcloud
image the package pins. Where a claim came from a command, the command is
printed with it.
Sibling of 2026-08-09-frappe-nextcloud-calendar-bridge.md,
which grows the app-dialect nextcloud socket. This one adds a second,
protocol-named socket to the same package, and §5 is the argument that the two
can coexist without repeating mailcow’s measured alias collision.
0. Measured, specified, owed
Section titled “0. Measured, specified, owed”| Class | Meaning | Marked |
|---|---|---|
| MEASURED | Read off pinned source or reproduced with a command, 2026-08-09 | plain statement, with its command |
| SPECIFIED | This document decides it; no code exists | ”the socket MUST…” |
| VERIFY | A concrete assumption with the one command that settles it | VERIFY |
| RULING OWED | An owner decision, not an agent’s to make | RULING OWED |
0.1 ★ The premise correction, first, because everything downstream moves
Section titled “0.1 ★ The premise correction, first, because everything downstream moves”The brief for this work said “Frappe has native Nextcloud backup upload.” It does not. Measured:
curl -L https://codeload.github.com/frappe/frappe/tar.gz/refs/heads/version-15 | tar xzgrep -rni nextcloud frappe-version-15/frappe | wc -l # → 0grep -rni webdav frappe-version-15/frappe | wc -l # → 0frappe-version-15/frappe/__init__.py:54 → __version__ = "15.117.0". Zero
occurrences of either word in the whole tree. The offsite backup targets frappe
core actually ships are exactly three, and they are enumerated in
frappe/hooks.py:267-294:
frappe.integrations.doctype.dropbox_settings.dropbox_settings.take_backups_dailyfrappe.integrations.doctype.s3_backup_settings.s3_backup_settings.take_backups_dailyfrappe.integrations.doctype.google_drive.google_drive.daily_backupls frappe-version-15/frappe/integrations/doctype/ confirms it: dropbox_settings,
s3_backup_settings, google_drive. No nextcloud_settings.
What exists instead is a separate bench app, published by Frappe the
organisation but shipped and versioned separately:
https://github.com/frappe/nextcloud-integration: app_name: nextcloud_integration, app_publisher: "Frappe", app_license: "MIT",
__version__ = '0.0.1', a single module, a single doctype, a single Python
file of ~180 lines, patches.txt empty. Its only dependency is frappe
(requirements.txt is the one word).
This matters for three reasons, and each one changes a decision later:
- The consumer side is a bake, not a config flip. Under the image-owned
ruling (2026-08-08) a frappe plug mechanism is baked into the image and
activated through vars, so this edge costs a third bench app in
frappe/docker/Dockerfile, besidefrappe_keycloakand thefrappe_nextcloudthe calendar bridge is landing. §8.4. - The app is unmaintained-shaped. Version
0.0.1, no patches,from __future__ import unicode_literalsand# -*- coding: utf-8 -*-headers throughout, Python-2-era boilerplate. It still works against v15 (§2.4 proves the four frappe APIs it calls are all present with compatible signatures), but nothing about its provenance says it is being kept in step. - Its bugs are ours to route around. §2.2 and §2.5 are two measured defects in it that the socket’s published data shape can avoid entirely, which is the single strongest argument for what this socket publishes.
Nothing here is a reason not to build the edge. It is a reason to build it against what the code does rather than against what the README says, because §2.2 is a case where those two disagree.
0.2 Measured, in one list
Section titled “0.2 Measured, in one list”frappe/nextcloud-integration@maincarries one Single doctype,Nextcloud Setting(issingle: 1), permissionsSystem Manageronly, with exactly fourteen entries infield_order, four of them layout breaks, so ten data-carrying fields, six of which arereqd: 1. §2.1 has the table.- Its transport is HTTP Basic auth over WebDAV:
session.auth = (self.nextcloud_username, self.get_password(fieldname='password')),session.verify = True. Methods used:PROPFIND(Depth 0),MKCOL,PUT. Success is201or204and nothing else. make_baseurl()doubles any explicit port and silently discards any path. Reproduced in §2.2 with a runnable transcription.- The pinned Nextcloud image maps
/remote.php/dav→ the current DAV endpoint and/remote.php/webdav→ the legacy one, fromremote.phpitself (§3.1). occ user:addon that image takes--password-from-env(NC_PASS/OC_PASS),--display-name,--group, and exits 1 withThe account "<uid>" already exists.rather than no-op, the same converge-on-failure shapedav:create-subscriptionhas (§4.3).- The engine’s alias-collision warning
X200931ALICOLfires only when one hostname resolves to two different services, not when two sockets share a hostname. Read offce/modules/app/integration_render.go:1314(§5.2). - mailcow’s
imap/smtppair is the precedent for two protocol sockets on one package, and mailcow’s own files record the collision measured 2026-08-07 that this design has to not repeat.
0.3 Evidence caveat, stated up front
Section titled “0.3 Evidence caveat, stated up front”The Nextcloud reads in §3 and §4 were taken from nextcloud:34.0.2-apache
pulled fresh on 2026-08-09, which resolved to
sha256:d7666d54d87c58d52869ddda36d1acbd4a7f53faf8ab6b91293daf204f3434e8.
apps/collaboration/nextcloud/vars.yaml:29 pins
sha256:58bc73331d541e0efe46c517ff7539e2e43427342b2a2feeb013b186fb4f3ecd.
Those are different digests for the same tag; the tag has been re-pushed
since the pin was taken. Nothing read here is version-sensitive (the occ
argument surface and remote.php’s route map are stable across 34.x point
releases), but the reads are not literally against the pinned bytes, and
saying so is cheaper than being caught. VERIFY on the estate with
docker run --rm --entrypoint sh nextcloud@sha256:58bc7333… -c 'grep -n "webdav" /usr/src/nextcloud/remote.php'.
1. What this edge is for
Section titled “1. What this edge is for”ERPNext holds the books. Its backups are the only artifact whose loss is
unrecoverable, and today the frappe package’s backup.yaml is the whole
answer: SHC’s own capture, into SHC’s own repository, on SHC’s own schedule.
That is one basket. The estate memory records that neither production estate has an automated backup schedule at all (measured 2026-08-07), which makes the argument for a second, independent, application-authored copy stronger than it would otherwise be: a copy that a frappe operator can see, restore from a laptop, and verify without any SHC tooling in the loop.
Nextcloud is already the estate’s file plane and already federated onto
people’s machines. Depositing the site’s own bench backup output there is
the cheapest second basket available.
Scope, stated so it is not quietly widened later. This edge is a
deposit: frappe writes archives into a WebDAV collection. It is not a
restore path, not a sync, not a shared filespace, and it does not make
Nextcloud a party to SHC’s backup doctrine. make migrate, never flatten;
SHC’s own repository stays the primary. This is a secondary copy, and the
socket’s own text must say so, because an operator who reads “backups go to
Nextcloud” and concludes the SHC repository is redundant has been misled by
our packaging.
2. What the consumer actually needs, measured, field by field
Section titled “2. What the consumer actually needs, measured, field by field”Everything in this section is read off
frappe/nextcloud-integration@main, file
nextcloud_integration/nextcloud_integration/doctype/nextcloud_setting/nextcloud_setting.{py,json}.
2.1 The Single doctype and its fields
Section titled “2.1 The Single doctype and its fields”issingle: 1, track_changes: 1, module: Nextcloud Integration,
permissions: System Manager (create/read/write/delete/print/email/share).
| field | type | reqd | default | what it is |
|---|---|---|---|---|
enabled | Check | 0 | the master switch; start_taking_backup returns immediately when false | |
nextcloud_username | Data | 1 | the Basic-auth user | |
password | Password | 1 | the Basic-auth secret; read via get_password(fieldname='password', raise_exception=False) | |
nextcloud_url | Data | 1 | origin only; see §2.2 | |
webdav_url | Data | 1 | the DAV path, leading/trailing slashes optional | |
path_to_upload_folder | Data | collection under the DAV root; empty ⇒ Frappe Backups | ||
backup_frequency | Select | 1 | Daily | options are exactly Daily and Weekly |
backup_files | Check | 0 | also upload the public/private file tarballs | |
send_notifications_to | Data (Email) | 1 | recipient of the status mail | |
send_email_for_successful_backup | Check | 0 | failures always mail; successes only when set |
★ Six reqd: 1 fields is a packaging constraint, not trivia. A
configure job that writes only the four connection fields and leaves
send_notifications_to empty will fail the Single’s save with a mandatory-field
ValidationError. The plug MUST carry an address; §8.2 defaults it from the
already-bound smtp edge and refuses with a named cause when there is none.
★ backup_frequency has no “off”. Unlike s3_backup_settings, whose
frequency Select includes None, this one offers Daily|Weekly only. The
only way to stop scheduled uploads is enabled = 0. That is what the
unintegration job must write (§8.3), not a frequency change, which cannot
express it.
2.2 ★ The URL shape, and the two defects that fix the socket’s data keys
Section titled “2.2 ★ The URL shape, and the two defects that fix the socket’s data keys”make_baseurl() is seventeen lines including its signature, and both of this
edge’s hard constraints live in them. Transcribed verbatim and run:
def make_baseurl(nextcloud_url, webdav_url): vurl = urlparse(nextcloud_url) if not vurl.scheme: return None if not vurl.netloc: return None if not vurl.port: port = 443 if vurl.scheme == 'https' else 80 base_url = '{0}://{1}:{2}'.format(vurl.scheme, vurl.netloc, vurl.port if vurl.port else port) ...urlparse(...).netloc already contains the port, and the format string
appends it again. Measured output:
nextcloud_url | resulting base URL |
|---|---|
https://cloud.example.com | https://cloud.example.com:443/remote.php/dav/files/admin/ |
http://prod.nextcloud.mystack | http://prod.nextcloud.mystack:80/remote.php/dav/files/admin/ |
http://prod.nextcloud.mystack:80 | http://prod.nextcloud.mystack:80:80/… ❌ |
https://cloud.example.com:8443 | https://cloud.example.com:8443:8443/… ❌ |
https://cloud.example.com/subpath | https://cloud.example.com:443/remote.php/dav/files/admin/ ❌ path gone |
prod.nextcloud.mystack | None ⇒ error_log.append('Nextcloud URL incorrect') |
Three constraints fall straight out, and each one is a socket data decision rather than a job-side workaround:
- The published origin MUST carry no explicit port. Not
:443, not:80, not a non-standard one. A ported origin is not “slightly wrong”; it produces an authority no resolver can parse and every upload fails. Fortunatelynextcloud.socket.yaml’sinternalUrlis already port-less (http://{{ environment }}.nextcloud.{{ stack }}), so the in-fabric posture is safe by construction. The public posture is not:vars.publicUrlis operator-authored and may carry anything. §8.1 makes the socket refuse a ported origin rather than publish it. - A path-routed Nextcloud cannot be expressed at all. The path is
discarded silently, so the archives would be PUT at the wrong origin and
404. This is the same refusal
nextcloudPicker.plug.yamlalready makes for a path-routed picker, for the same reason: one constant cannot carry two meanings, and degrading is worse than refusing. Refuse, and name it. - The origin and the DAV path are two fields, so publish two keys. The
consumer’s configuration surface is
nextcloud_url+webdav_url. A socket that published only a joinedurlwould force the configure job to split it in POSIX sh, parameter-expansion string surgery on a URL, which is exactly the fragile thingnextcloudPicker.plug.yamlhad to write and then guard. Publishing the split as the primitive costs one data key and removes the shell entirely. §6.
Leading/trailing slashes on webdav_url are normalised by make_baseurl
('/remote.php/dav/files/admin', 'remote.php/dav/files/admin/' and
'/remote.php/dav/files/admin/' all produce the same base). So the socket may
publish whichever form reads best; it must still pick one and stick to it,
because §8.5’s read-back compares stored strings.
2.3 What it does on the wire
Section titled “2.3 What it does on the wire”PROPFIND <base><folder> Depth: 0 allow_redirects=False 404 and path_to_upload_folder set → frappe.throw('Given "Path to upload folder" does not exist') 404 and it is unset → MKCOL <base>Frappe BackupsPUT <base><folder>/<filename> allow_redirects=False 201 or 204 → "Success"; anything else → "Failed"Four consequences worth stating, because three of them are the difference between an edge that works and one that reports success while doing nothing:
-
MKCOLcreates one level. Apath_to_upload_foldernaming a nested collection whose parent does not exist gets a 409 from the server, and the code only branches on 404. So either the operator pre-creates the tree, or the collection is single-segment. The socket’s own default MUST be single-segment. -
allow_redirects=Falseeverywhere. An ingress that 301shttp→https, or a Nextcloud behind a redirecting proxy, produces a 301 which is neither 201 nor 204 ⇒"Failed". In-fabric plain HTTP has no redirect and is the safe posture; §8.1 says so. -
session.verify = True. A public origin fronted by a private CA fails TLS verification.upload_backupswallows every exception and returns the string"Failed"with no cause, so the operator gets a failure email naming nothing.check_for_upload_folderdoes not catch, so its TLS error at least reaches the traceback in the failure mail. In-fabric HTTP sidesteps the whole class. -
★ An absent file is scored as a success.
upload_backupopens withif not os.path.exists(filebackup): return, an implicitNone. The caller comparesif db_response == 'Failed', andNone == 'Failed'is false, so a file that was not there is indistinguishable from an upload that worked, andsend_email_for_successful_backupwill happily mail “Backup Uploaded Successfully”. Narrow (it needs the archive to vanish between generation and upload) but real, and it is the reason §8.5’s read-back verifies against Nextcloud, never against the app’s own report.Its sibling is safe: when
get_recent_backupreturnsNone,os.path.exists(None)raisesTypeError(verified on CPython 3.14.4: “stat: path should be string, bytes, os.PathLike or integer, not NoneType”), which the outerexcept Exceptionturns into a failure email with a traceback. Loud, not silent.
2.4 It still fits frappe v15, checked, not assumed
Section titled “2.4 It still fits frappe v15, checked, not assumed”The app imports four things out of frappe. All four are present in 15.117.0 with compatible signatures:
| import | v15 location | signature check |
|---|---|---|
frappe.utils.backups.new_backup | backups.py:587 | new_backup(older_than=6, ignore_files=False, …, force=False, …); the app passes ignore_files= and force= by keyword ✓ |
BackupGenerator.get_recent_backup | backups.py:258 | get_recent_backup(self, older_than, partial=False); the app passes older_than=24*30 ✓ |
offsite_backup_utils.send_email | offsite_backup_utils.py:11 | send_email(success, service_name, doctype, email_field, error_status=None); the app’s 4- and 5-arg calls both fit ✓ |
offsite_backup_utils.validate_file_size | same file | validate_file_size() ✓ |
★ And one behaviour worth recording because it looks like a bug and is not.
validate_file_size() sets frappe.flags.create_new_backup = True, then
clears it to False when the newest existing database archive exceeds 1 GB.
prepare_backup passes that flag as force=. So on a site over 1 GB the app
reuses a dump taken in the last 6 hours instead of taking a fresh one
(new_backup’s default older_than=6 → BackupGenerator.get_backup(6, …, force=False)). On a daily cadence the previous dump is 24 hours old, so a
fresh one is taken anyway. It is a de-duplication, not staleness, but it does
mean “Backup Now” twice in a row on a large site uploads the same archive
twice, and an operator proving the edge should not read that as a failure.
get_recent_backup(older_than=720) is a maximum staleness, not a
lookback: old_enough() returns the file only when is_file_old(path, 720)
is false. An archive older than 30 days is returned as None, which lands on
the loud TypeError path above.
2.5 The cadence, and what it depends on
Section titled “2.5 The cadence, and what it depends on”hooks.py registers exactly two scheduler events:
scheduler_events = { "daily": ["…nextcloud_setting.daily_backup"], "weekly": ["…nextcloud_setting.weekly_backup"],}and each calls take_backups_if(freq), which compares
frappe.db.get_single_value("Nextcloud Setting", "backup_frequency") to its
own name. So a Weekly setting makes the daily hook a no-op, and vice versa.
This depends on the frappe scheduler being live, which the calendar-bridge
document already flags as a restore-carried hazard: frappe.exporter.yaml
names pause_scheduler and scheduler_enabled as source-deployment posture a
restore must not carry in. A paused scheduler makes this edge a configuration
that never fires and never says so. §8.5’s preflight asserts it, and §9’s
acceptance list proves it with a manual trigger rather than by waiting a day.
take_backup() is @frappe.whitelist()-decorated and enqueues
start_backup on the long queue with timeout=1500. That is the handle an
acceptance test uses; it needs no UI.
★ There is no retention. Every run PUTs a fresh timestamped filename into
one collection and nothing ever deletes. The collection grows without bound
inside whatever quota the deposit account has. A quota is therefore not a
nicety; it is the only backstop, and §4.2 makes setting one part of the
provision. RULING OWED in §11 on whether SHC should also prune.
3. Why the stem is webdav, not nextcloud
Section titled “3. Why the stem is webdav, not nextcloud”docs/app-development/plugs-and-sockets.md states the rule and, more usefully,
states the test. Both questions are asked and answered here.
3.1 Question 1: could a second, unrelated implementation serve it?
Section titled “3.1 Question 1: could a second, unrelated implementation serve it?”WebDAV is RFC 4918, an IETF wire protocol with many independent servers
(Apache mod_dav, nginx’s dav module, ownCloud, Seafile, Synology, and every
commercial “WebDAV endpoint” a consumer might be pointed at). The consumer in
§2 does not know it is talking to Nextcloud: it sends PROPFIND, MKCOL and
PUT with Basic auth and branches on 201/204/404. Nothing in
nextcloud_setting.py reads an OCS route, a capability document, or any
Nextcloud-specific header. The one Nextcloud-flavoured thing it does
(session.headers.update({"OCS-APIRequest": "true"})) is set on a session that
only ever performs DAV verbs, where the header is inert.
Measured from the pinned image, Nextcloud’s own DAV surface is two mounts,
read off /usr/src/nextcloud/remote.php:
'webdav' => 'dav/appinfo/v1/webdav.php', # /remote.php/webdav (legacy)'files' => 'dav/appinfo/v1/webdav.php', # /remote.php/files (legacy alias)'dav' => 'dav/appinfo/v2/remote.php', # /remote.php/dav (current)The current endpoint’s files collection is /remote.php/dav/files/<uid>/,
the form Nextcloud’s own Files settings pane prints, and the form the app’s
README names (imprecisely, as /remote.php/dav/files/{email_address}/; the
path segment is the uid, which equals the email only for accounts created
with an email as the login).
★ The legacy /remote.php/webdav endpoint takes no uid; it serves the
authenticated principal’s own root. That is a genuinely useful property for a
socket whose whole job is substitutability, because it makes the published
path independent of the account name. It is not the recommended endpoint
though, and VERIFY before adopting it:
curl -u "$USER:$APPPASS" -X PROPFIND -H 'Depth: 0' \ http://<nc>/remote.php/webdav/ -o /dev/null -w '%{http_code}\n' # expect 207Answer to question 1: yes.
3.2 Question 2: is external-webdav nameable?
Section titled “3.2 Question 2: is external-webdav nameable?”Trivially. apps/standalone/ already carries external-imap, external-smtp,
external-s3, external-postgres, external-mysql, external-mongodb,
external-redis, external-oidc, external-llm, nine shims, each serving a
socket stem identical to its own suffix, each publishing coordinates an
operator pasted in and running no service of its own. external-webdav would
publish an origin, a path, a username and a password; it is a vars.yaml and a
socket file. That is precisely the shape of a WebDAV deposit target: an
operator with a Hetzner Storage Box, an ownCloud, or a rented WebDAV space
pastes four values and the frappe plug cannot tell the difference.
That is question 1 made operational, and the shim passes it without strain.
Answer to question 2: yes.
3.3 So why not just grow nextcloud?
Section titled “3.3 So why not just grow nextcloud?”Because the socket’s own header already drew the line and it lands on the other side of it:
a SINGLETON socket carrying the bare app name … this is Nextcloud’s own surface (WebDAV under /remote.php/dav, OCS under /ocs/v2.php, the bearer contract user_oidc’s oidc plug configures), not a substitutable wire protocol.
The nextcloud socket’s contract is “act inside Nextcloud with Nextcloud’s
own admin authority”: OCS user enumeration, an admin app password, a read-back
of a dav app-config knob. Every one of those keys is meaningless to a second
implementation. A backup deposit is the opposite: it needs a URL, a login and a
password, and it needs to not care what is behind them.
The tell is the plug. A frappe deployment binding -i nextcloud=<stack> gets
the discovery half of an app-dialect socket and, if it declares a label, an
admin-equivalent credential (the socket says so in as many words: “IT IS
NOT A SCOPED CAPABILITY, AND CALLING IT ONE WOULD BE A LIE”). Asking for that
in order to upload a tarball would be the estate’s most privileged secret
issued to its least privileged verb. §4 is that argument in full.
This is also the second half of a rule the catalog already applies to mailcow:
one app, one dialect socket (mailcow, the REST admin API) plus protocol
sockets beside it (smtp, imap) that external-* shims can serve. Nextcloud
gets exactly the same treatment (nextcloud for the dialect, webdav for the
protocol), and for exactly the same reason.
4. The credential, and no, the existing grant does not cover it
Section titled “4. The credential, and no, the existing grant does not cover it”4.1 What the grant would give, and why it is the wrong shape
Section titled “4.1 What the grant would give, and why it is the wrong shape”nextcloud.socket.yaml’s grant-nextcloud-admin mints a 72-character app
password on vars.adminUser via occ user:auth-tokens:add. Mechanically it
would work here: Nextcloud accepts app passwords as the password half of
Basic auth on DAV, and /remote.php/dav/files/<adminUser>/ is a writable
collection. Nothing would fail.
That is the problem. Measured, from the socket’s own header:
occ exposes no
--scopeon this command, so the token carries the admin account’s full authority: a holder can read every file in the instance and create or delete users.
The capability being purchased is “append files to one collection”. The
credential on offer is “read every file in the instance and create or delete
users”. That gap is not a rounding error, and unlike the calendar bridge’s
observation problem there is no argument from necessity: the calendar
bridge needs /cloud/users, which is admin-or-subadmin only, so the admin
grant is the only headless path Nextcloud offers. A DAV deposit needs no
admin surface at all. A plain user’s own DAV home is the scoped capability,
and it already exists.
So the answer to “does the existing nextcloud admin grant cover it” is:
yes mechanically, no doctrinally, and this is one of the rare cases where
those diverge and the doctrinal answer should win, because taking the grant
here means holding admin authority in a job whose entire job is PUT.
4.2 What the socket provisions instead: SPECIFIED
Section titled “4.2 What the socket provisions instead: SPECIFIED”A dedicated, non-admin, quota-bounded Nextcloud account whose only purpose is to own the deposit collection. Measured against the pinned image:
# core/Command/User/Add.php on nextcloud:34.0.2-apacheocc user:add --password-from-env --display-name "SHC backup deposit" <uid># uid must match [a-zA-Z0-9_@-]+ ("must only contain a-z, A-Z, 0-9, -, _ and @")# password read from NC_PASS, falling back to OC_PASS# exits 1, "The account "<uid>" already exists."; never a no-opocc user:setting <uid> files quota "50 GB"Two of those lines are load-bearing:
- ★
user:addfails rather than no-ops on an existing account, exactly likedav:create-subscription. So the provision job creates, reads the failure text as converged, and never asks “does it exist” on the happy path. Same measured shape, same converger discipline, and it is worth noticing that this is now the second place in this package where Nextcloud’s CLI expresses idempotence as exit 1. - The quota is the only bound on §2.5’s unbounded growth.
user:setting <uid> files quota <value>;Setting.phpon the same image takes<uid> <app> <key> <value>with--update-only,--deleteand--error-if-not-existsoptions. Setting it is part of the provision, not an operator afterthought.
VERIFY, and it decides whether the provision needs a second step: user:add
calls Filesystem::init($uid, '') only when --group is passed
(Add.php, the if (!empty($groups)) branch). A fresh account with no group
may therefore have no materialised home until something touches its
filesystem. The app’s own first act is a PROPFIND on the collection, which
should force it, but prove it rather than assume:
occ user:add --password-from-env --display-name t probe-usercurl -u 'probe-user:<pw>' -X PROPFIND -H 'Depth: 0' \ http://localhost/remote.php/dav/files/probe-user/ -o /dev/null -w '%{http_code}\n'# expect 207 on the first call, not 404If it does not, the fix is one flag: give the account a group.
4.3 Why the credential is published, not minted per consumer
Section titled “4.3 Why the credential is published, not minted per consumer”The nextcloud socket mints per consumer over the mint-and-return channel,
keyed on an opt-in label. This socket does not, and the reason is the same
one imap.socket.yaml gives for its contract (1):
SHARED RELAY MAILBOX:
username/password. One credential, the stack’s own noreply mailbox, provisioned by mailcow-provision-smtp. Correct for SYSTEM consumers …
A protocol socket publishes coordinates in data:. That is what makes
external-webdav possible at all: a shim that runs no service cannot mint
anything, so any key only a real provider could produce is a key the shim must
publish empty and every consumer must guard. Minting would make the socket
un-shimmable, which is the one property §3 spent its whole argument
establishing.
The cost, stated plainly: one credential, shared by every consumer that
binds webdav on this provider. Two frappe stacks depositing into one
Nextcloud share a login and a collection. That is acceptable for a deposit
account whose authority is one directory, and it is not acceptable for
anything with a wider reach, which is the boundary the socket header must
draw, in the same voice imap.socket.yaml draws it.
RULING OWED (§11): whether a per-consumer app password on the deposit
account, gated on an optional label exactly as the nextcloud socket gates
its admin grant, should be the growth path. It is cheap (the same occ user:auth-tokens:add, just on a non-admin uid instead of admin), and it
would give per-consumer revocation without touching the shared account. It is
proposed, not designed, because nothing needs it yet and a second consumer is
what should trigger it.
5. Two sockets, one app, and the alias collision, measured
Section titled “5. Two sockets, one app, and the alias collision, measured”This is the mechanical question the design has to clear before it can ship, so it gets its own section and an exact answer.
5.1 What mailcow measured, and why it hurt
Section titled “5.1 What mailcow measured, and why it hurt”Both mailcow protocol sockets publish the same rendered hostname, and both files carry the identical warning:
the engine attaches data.hostname as a network alias on this service, and
smtp.socket.yamlattaches the SAME rendered hostname onpostfix-mailcow; docker DNS returns both A records in rotating order and a wrong-A connect REFUSES (measured 2026-08-07: dovecot answering :587 refused, postfix answering :993 refused).
The failure is not “the hostname is ambiguous”. It is that the two sockets front different services, so half the connections land on a container that is not listening on the port the caller dialled. The files also record why neither obvious fix is available there: distinct in-fabric names break TLS verification and off-fabric dials of the same socket data, and a fronting TCP proxy would sit in every mail path.
5.2 The engine’s guard, and exactly when it fires
Section titled “5.2 The engine’s guard, and exactly when it fires”ce/modules/app/integration_render.go, in the loop that attaches socket
hostnames as network aliases:
if prior, clash := aliasedBy[hostname]; clash && prior != serviceName { corelog.Warn(ctx, X200931ALICOL(stack, hostname, prior, serviceName))} else { aliasedBy[hostname] = serviceName}and the error’s own header (errors.go:1759):
two sockets of one provider package render the SAME hostname onto DIFFERENT services … The attach proceeds; half-working resolution beats none, but the collision is a package defect only its author can fix.
★ The predicate is prior != serviceName. Two sockets sharing a hostname
and resolving to the same service take the else branch and re-record the
same mapping: no warning, no collision, nothing to fix. The hazard is
service divergence, not socket count.
5.3 Why this pair is safe, and how to keep it that way
Section titled “5.3 Why this pair is safe, and how to keep it that way”apps/collaboration/nextcloud/compose.yaml declares three services:
nextcloud, valkey, nextcloud-pgclient. Only one of them speaks HTTP, and
both DAV and OCS are served by the same PHP application on the same port. So
webdav.socket.yaml and nextcloud.socket.yaml front the same service and
the guard cannot fire.
That safety is conditional on one line, and the line is easy to omit:
service: nextcloud # REQUIRED. Without it resolveSocketService falls to the # socket file stem ("webdav", not a service here) and # then to the sorted-first heuristic, which reports # X200930SOKSVC on every install.Measured from resolveSocketService (integration_render.go:1776): declared
name first, then the socket stem, then sort.Strings(names)[0] with
guessed=true. Sorted-first here happens to be nextcloud ("nextcloud" < "nextcloud-pgclient" < "valkey"), so omitting service: would still resolve
correctly, and would still emit a soft warning on every install, and would
still be one renamed service away from silently pointing the socket at
nextcloud-pgclient. Declare it.
The remaining choice is whether webdav publishes the same hostname or its
own. The same one ({{ environment }}.nextcloud.{{ stack }}), because it
is literally the same HTTP endpoint, because two aliases on one service buy
nothing, and because a webdav-flavoured alias would invite a future reader to
believe the two sockets front different things. A guard is added (§8.6) that
asserts both sockets in this package resolve to the same service:, so the day
someone splits DAV onto a second container the tree goes red before the estate
does.
5.4 What the mailcow precedent actually teaches
Section titled “5.4 What the mailcow precedent actually teaches”Not “avoid two sockets per package”; mailcow ships three and the catalog is better for it. The lesson is narrower and it is the one this design applies: the hostname is a property of the fronting service, not of the socket. Two sockets may share a hostname iff they share a service. When they do not, the package owes either distinct hostnames or a fronting service, and mailcow’s own files are the record of what it costs when neither is available.
6. What the socket publishes: SPECIFIED
Section titled “6. What the socket publishes: SPECIFIED”schema: socket: hostname@string!: In-fabric hostname the engine aliases onto the provider's HTTP service origin@url!: Scheme + host, NO PORT and NO PATH; see the constraint at the data key davPath@string!: Absolute DAV path under that origin, with a leading and trailing slash url@url!: Convenience join, `origin + davPath`. Equal by construction; never re-derive it username@string: Deposit account login (empty when the provider grants no account) password@secret: Deposit account secret (empty likewise); guard every read with `| default('')` collection@string: Collection under davPath the consumer should write into (single segment) quota@string: Advertised quota on the deposit account, informational; empty means unknownNotes that belong on the keys themselves, each because something measured demands it:
origincarries no port and no path. Not a preference: §2.2 measured a consumer that doubles the port and discards the path. Any provider serving this stem inherits the constraint, so it belongs in the schema text rather than in one consumer’s job.originanddavPathare the primitives;urlis the convenience. The known consumer configures the two halves separately, and splitting a URL in POSIX sh is precisely the fragilitynextcloudPicker.plug.yamldocuments. Publishing all three costs one string and removes an entire class of job-side parsing.username/passwordare optional and every consumer MUST| default('')-guard them, the contractimap.socket.yamlstates for its mailcow-only keys, for the same reason: a shim publishes what the operator pasted and nothing else.collectionis single-segment by default, becauseMKCOLcreates one level (§2.3) and the consumerfrappe.throws on a missing multi-level path.quotais advertised, not enforced, the same posturecalendarRefreshRatetakes on the sibling socket. It tells a consumer how much room it has; it promises nothing.
Deliberately absent, so it is not relitigated:
- No OCS anything. OCS is the dialect socket’s business. A
webdavconsumer that wants to enumerate users is in the wrong socket. - No
labeland no mint channel. §4.3. Adding one later is additive and is the growth path the ruling in §11 decides. - No
publicUrl. A deposit that leaves the fabric is a different posture with different failure modes (TLS verification, redirects, egress policy). If it is wanted, it isvars.webdav.originon the provider, published through the sameoriginkey, and §8.1’s ported-origin refusal is what keeps it honest.
7. How it coexists with the nextcloud socket at bind time
Section titled “7. How it coexists with the nextcloud socket at bind time”One provider now offers two stems, and a consumer picks by name. Three mechanics decide what that feels like, and all three already exist:
7.1 Auto-match still works, and still only when it is unambiguous.
-i <provider> auto-matches “only if exactly one of the consumer’s plugs
matches one of the provider’s sockets by name”
(plugs-and-sockets.md, the integration-ref table). A frappe stack that
declares both nextcloud.plug.yaml (calendar) and webdav.plug.yaml
(backup) therefore cannot be bound with a bare -i nextcloud=<stack>; it must
name the plug: -i webdav=<stack>, -i nextcloud=<stack>. That is correct
behaviour, and the packaging owes it a sentence in the app README rather than
an operator discovering it from a refusal.
7.2 The two edges are independent and must stay that way. Binding webdav
grants no admin credential; binding nextcloud deposits no backups. Neither
plug may read the other’s data. A consumer that wants both binds both, and
required: false on each keeps a missing one from blocking an ERP install.
7.3 They share exactly one thing: the provider’s readiness. Both need
status.php to answer installed:true and maintenance:false. The existing
socket already waits on both (its grant job polls for ~5 minutes and refuses
with a named cause). webdav’s discovery job should reuse the same
context: http probe against internalUrl/status.php, same shape, same
budget, no new mechanism.
8. The exact SHC surfaces: all SPECIFIED, none of them exist
Section titled “8. The exact SHC surfaces: all SPECIFIED, none of them exist”8.1 apps/collaboration/nextcloud/webdav.socket.yaml: new
Section titled “8.1 apps/collaboration/nextcloud/webdav.socket.yaml: new”service: nextcloud # REQUIRED; §5.3
data: hostname: "{{ environment }}.nextcloud.{{ stack }}" origin: "{{ vars.webdav.origin | default('http://' ~ environment ~ '.nextcloud.' ~ stack) }}" davPath: "/remote.php/dav/files/{{ vars.webdav.user | default('shc-deposit') }}/" url: "{{ vars.webdav.origin | default('http://' ~ environment ~ '.nextcloud.' ~ stack) }}/remote.php/dav/files/{{ vars.webdav.user | default('shc-deposit') }}/" username: "{{ vars.webdav.user | default('shc-deposit') }}" password: "{{ vars.webdav.password }}" # @secret, ref+vault://…?autogen collection: "{{ vars.webdav.collection | default('backups') }}" quota: "{{ vars.webdav.quota | default('') }}"url repeats the join rather than referencing origin because a data key
cannot reference a sibling data key, the same constraint the existing socket
records where it spells internalUrl and ocsUrl out twice, and gitlab’s
socket does the same. A guard (§8.6) asserts the two spellings agree.
jobs.discovery: one context: http probe on
{{ integration.socket.data.origin }}/status.php, max_retries: 60,
retry_interval: 3. Same as the sibling socket’s.
jobs.integration: provision-webdav-deposit, context: service,
service: nextcloud, user: www-data (occ refuses to run as root; www-data
owns config.php on this image). No timeout: field; the socket
integration job struct has none, so writing one parses and then vanishes; the
waits carry their own budgets. In order:
-
Refuse a ported or path-carrying origin, loudly. §2.2 is not a warning, it is a hard stop:
Terminal window # A port survives into the consumer's URL builder twice and a path not at# all; both produce an authority no upload can reach. Refusing here is the# only place the operator still has the value in their hand.case "$${ORIGIN}" inhttp://*:*/* | https://*:*/* | *://*:[0-9]*) BAD=port ;;esacREST="$${ORIGIN#*://}"case "$${REST}" in */*) BAD=path ;; esacwith a message naming which of the two it is and what to set instead.
-
Wait for
occ status --output=jsonto reportinstalled:trueandmaintenance:false, exactly asgrant-nextcloud-admindoes and for the reason it records: during anocc upgrade,status.phpstill says installed while every HTTP route answers 503. -
Provision the deposit account, reading
The account "<uid>" already exists.(exit 1) as converged, never as failure.NC_PASSfrom the@secretvar;--display-nameset; quota applied whenvars.webdav.quotais non-empty. -
Read the account back;
occ user:info <uid> --output=jsonmust show it enabled, and it must not be in theadmingroup. The account being accidentally admin is the one outcome that silently converts a scoped capability into the thing §4.1 refused; assert against it rather than assume the create was clean. -
Prove the capability, not the credential, the discipline the sibling socket already enforces on its OCS preflight.
PROPFINDthe collection as the deposit account overhttp://localhost, withHost:read offocc config:system:get trusted_domains 0(the image installstrusted_domains[0] = localhost; an untrusted Host is answered with an error page). A 207 is the proof.MKCOLthe collection when the PROPFIND is 404, then PROPFIND again; the write is never trusted by its exit code. -
Print a one-line summary: provisioned / converged, quota, collection.
jobs.unintegration: report-webdav-deposit-retained. It reports, it does
not delete, and the reason is the same one that keeps lifetime: managed
off the sibling’s revoke job, arrived at from the other side: this collection
holds an operator’s backups. Deleting a user-visible archive on a detach is
the destructive half of the class the estate has already been burned by. So
the job says what remains, names the two commands (occ user:delete <uid>,
or empty the collection from the Files UI), and exits 0. RULING OWED in §11
on whether it should at minimum disable the account, which stops future
deposits without destroying past ones.
8.2 apps/platform/frappe/webdav.plug.yaml: new
Section titled “8.2 apps/platform/frappe/webdav.plug.yaml: new”required: false # a backup target must never block an ERP install
services: - frappe-web # the site DB connection and the bench live here; # frappe DIALS OUT to Nextcloud, so no inbound alias # is needed and none is claimed
data: collection: "{{ vars.webdav.collection | default('') }}" # empty ⇒ the socket's notifyEmail: "{{ vars.webdav.notifyEmail | default('') }}" # ⇒ reqd field, §2.1 frequency: "{{ vars.webdav.frequency | default('Daily') }}" # Daily|Weekly ONLY backupFiles: "{{ vars.webdav.backupFiles | default(false) }}"⚠ {{ stack }} in a plug data: render is the PROVIDER’s stack, not this
one (sonarqube/gitlab.plug.yaml documents the trap; ce builds plugCtx with
"stack": sp.ProviderStackName). Nothing above derives from stack, and nothing
added later may; tenant is the consumer’s, stack names the Nextcloud.
jobs.post_deployment carries the configure job (§8.3);
jobs.unintegration carries the disable job.
8.3 The consumer-side configure job
Section titled “8.3 The consumer-side configure job”frappe-configure-webdav-backup, context: service, service: frappe-web.
It follows frappe-configure-keycloak-connector and
frappe-install-picker-client-script because both already solved the shape:
-
Refuse if the app is not on the bench, in the IMAGE-OWNED language the bats guard pins, never suggesting a vdeployment, never running
bench get-app:Terminal window if ! ./env/bin/python -c "import nextcloud_integration" 2>/dev/null; thenecho "the webdav backup edge was requested but nextcloud_integration is not on this bench." >&2echo "Plug mechanisms are IMAGE-OWNED (owner ruling 2026-08-08): baked in, activated" >&2echo "through vars, never installed as vdeployments. Point images.frappe at an image" >&2echo "that bakes nextcloud_integration." >&2exit 1fi -
bench --site <s> install-app nextcloud_integrationwhen absent. Safe per the corrected rule in the Dockerfile header: the code is already importable, so registration has no import window. -
Write the Single.
frappe.client.set_valueon a Single works, but all sixreqdfields must be present in one save or the mandatory check fails, so the job builds one payload and writes it once, and it builds it withjson.dumps+ast.literal_evalfor the reason the picker plug records:bench execute --kwargsis evaluated as a Python literal, not parsed as JSON, sotrue/false/nullareNameErrors and every boolean must be an int. -
Read back and fail loudly; re-read the stored Single and assert
enabled == 1, thatnextcloud_urlis exactly the publishedorigin, and that the storedpassworddigest matches the one sent (never echo it). House discipline: no write in this catalogue is trusted by its exit code, and §2.3’s silent-success path is the local reason. -
Prove the deposit end to end, once.
bench --site <s> execute nextcloud_integration.…nextcloud_setting.take_backupenqueues on thelongqueue; the job then polls the collection over WebDAV for a new object. This is the step that catches a paused scheduler, a wrong quota, a redirecting ingress and a TLS refusal, all four of which otherwise present as “configured, and nothing ever arrives.”
Why activation lives here and not in vars.activateApps. Same argument the
calendar bridge makes: activateApps is for apps every site should carry
regardless of edges. This one is meaningful only when a webdav edge exists,
and activating it estate-wide would put a backup uploader on benches with
nowhere to upload. Edge-scoped activation, edge-scoped teardown.
8.4 The bake, and the cost nobody should be surprised by
Section titled “8.4 The bake, and the cost nobody should be surprised by”frappe/docker/Dockerfile gains a third bench app, in the shape the first
two established (the file already carries frappe_keycloak at a pinned sha and
frappe_nextcloud at REPLACE_WITH_PUBLISHED_SHA, the calendar bridge’s
placeholder):
ARG NEXTCLOUD_INTEGRATION_REPO=https://github.com/frappe/nextcloud-integration.gitARG NEXTCLOUD_INTEGRATION_REF=<commit sha, never a branch>with the same git init / fetch --depth 1 / test "$(git rev-parse HEAD)" =
assertion, the same ./env/bin/pip install -e under USER frappe, the same
separate RUN proving import nextcloud_integration against
./env/bin/python, and nothing written under sites/ or logs/
(tests/unit/ci/frappe_image_volume_writes_test.go enforces that, because
Docker does not: under BuildKit a write to a VOLUME path persists into the
published image).
★ This app is a third-party pin at 0.0.1 with no release cadence, so the
sha is the version and there is nothing else to track. record-versions.sh
walks the bench and will pick it up; it must also be added to the provenance
manifest’s required-app list beside frappe, erpnext, frappe_keycloak and
frappe_nextcloud, or tests/unit/catalog/image_provenance_test.go will
happily pass an image that is missing it.
★ And the trap that must be stated with the delivery, every time: the bench
volume is seeded once. On an existing bakeApps: false deployment (the
default, and what both live production benches run), .seeded already exists,
so the new app does not arrive and there is no error. version-drift
reports stale and names it, which is the only reason the no-op is visible.
Delivering this to an existing vapp-mode bench needs a deliberate, consented
step. Bumping the pin is not that step and must not be reported as one.
★ A vendoring question this raises and does not answer. Three baked bench apps, one of them third-party and dormant, is the point at which “which apps does the SHC frappe image carry, and who decides” stops being obvious. That is a packaging ruling, not a socket decision, and it is §11.4.
8.5 apps/platform/frappe/vars.yaml: additions
Section titled “8.5 apps/platform/frappe/vars.yaml: additions”webdav: collection: "" # empty → the socket's own default notifyEmail: "" # empty → derived from the smtp edge; refused if neither frequency: "Daily" # Daily | Weekly ONLY; the doctype Select has no third option backupFiles: false # public + private file tarballs alongside the DB dumpand on the provider, apps/collaboration/nextcloud/vars.yaml:
webdav: origin: "" # empty → the in-fabric http origin. If set: NO PORT, NO PATH. user: shc-deposit # [a-zA-Z0-9_@-]+, occ user:add's own character class password: "ref+vault://webdav_deposit_password?autogen" collection: backups # single segment: MKCOL creates one level quota: "50 GB" # the ONLY bound on unbounded growth; this edge never pruneswith matching vars: type declarations in each app.yaml, each carrying the
constraint that governs it.
8.6 Guards to add
Section titled “8.6 Guards to add”| test | asserts |
|---|---|
apps/collaboration/nextcloud/tests/tests.bats | webdav.socket.yaml declares service: nextcloud, and every *.socket.yaml in the package declares the same service (the §5.3 invariant, stated as a property so a future third socket is caught) |
| same | data.url equals data.origin ~ data.davPath (the sibling-key duplication of §8.1) |
| same | data.origin’s default renders with no : after the host and no path segment |
| same | the unintegration job never deletes a collection or a user (grep for user:delete / DELETE verbs) |
apps/platform/frappe/tests/tests.bats | the new plug carries no vapp: (covered by the existing glob), required: false, services: pins frappe-web, the configure job says IMAGE-OWNED and never bench get-app |
| same | the plug’s data: uses tenant and never stack |
| same | every socket read in the configure job is ` |
tests/unit/catalog/image_provenance_test.go | the Dockerfile app set and imageVersions agree (existing test, new row) |
9. The phased plan
Section titled “9. The phased plan”9.1 Phase 1: a working deposit. Buildable today.
Section titled “9.1 Phase 1: a working deposit. Buildable today.”What ships: an operator runs shc update <frappe-stack> -i webdav=<nc-stack>
and the site’s daily backup lands in a quota-bounded Nextcloud collection, with
a failure email if it does not.
| # | Deliverable | Where | New component? |
|---|---|---|---|
| 1 | webdav.socket.yaml + provision job + report-only teardown | apps/collaboration/nextcloud/ | no, a new file using idioms already in the package |
| 2 | vars.webdav.* on the provider | apps/collaboration/nextcloud/vars.yaml, app.yaml | no |
| 3 | The nextcloud_integration bake + pin | frappe/docker/Dockerfile, apps/platform/frappe/vars.yaml | yes, a third baked bench app |
| 4 | webdav.plug.yaml + vars + the configure job | apps/platform/frappe/ | no |
| 5 | The guards | both tests.bats, image_provenance_test.go | no |
★ “No new component” is true of the SHC side and only the SHC side. There is no broker, no sidecar, no vApp, no daemon, no credential mint and no new Go. But item 3 is a real image change with a real delivery trap (§8.4), and unlike the calendar bridge there is no new code to write; the bench app already exists and is MIT. The honest summary is: one new socket, one new plug, one third-party pin.
Acceptance for phase 1 (each line is a command, not a feeling):
occ user:info shc-deposit --output=json→ enabled, quota as configured, not in theadmingroup.- A second
shc updateprovisions nothing and reports “converged”, the idempotency assertion, and the one most worth automating, because §4.2’s converge-on-exit-1 is the only thing making it true. bench --site <s> execute frappe.client.get_value --kwargs "…"shows the Single withenabled = 1andnextcloud_urlexactly equal to the socket’s publishedorigin, string-equal, because a:443that slipped in would look right and upload nothing.bench --site <s> execute nextcloud_integration.nextcloud_integration.doctype.nextcloud_setting.nextcloud_setting.take_backupthen, within a few minutes,curl -u shc-deposit:<pw> -X PROPFIND -H 'Depth: 1' <url><collection>/lists a*-database.sql.gznewer than the trigger.- With the scheduler paused (
bench --site <s> set-config pause_scheduler 1), the configure job’s preflight refuses and names it rather than reporting a configured edge. shc update <frappe-stack> -i webdav!leavesenabled = 0on the Single, the collection intact, and a teardown message naming what remains.- A deliberately ported origin (
--var webdav.origin=https://cloud.example.com:443) makes the provision job refuse with the port named, not publish.
9.2 Phase 2: the things phase 1 knowingly does not do
Section titled “9.2 Phase 2: the things phase 1 knowingly does not do”- Per-consumer credentials on the deposit account, gated on an optional
label, using the sameocc user:auth-tokens:addthe sibling socket uses (§4.3). Trigger: a second consumer. - Retention. §2.5: nothing prunes, ever. Options are a Nextcloud-side
retention job (
occhas no such command; it would be acrons:entry running a DAV sweep), a quota that simply fills and starts failing loudly, or an explicit refusal to manage it.RULING OWED§11.3. external-webdav. The shim is what makes the stem’s name honest, and writing it is avars.yamlplus a socket file with no jobs. It is not in phase 1 only because nothing needs it yet, but note the ratchet:scripts/arch-fitness.shcheck 22’sexternal-shim-socket-stemhas a ceiling of 0 and would be satisfied on the day it lands, since the stem already matches.- A restore path. Explicitly out of scope in both phases.
bench restorefrom a WebDAV URL is a different verb with a different blast radius, and the migration doctrine (make migrate, never flatten) governs it.
9.3 Out of scope for both phases
Section titled “9.3 Out of scope for both phases”Nextcloud → frappe of any kind. Per-user file spaces. Nextcloud External Storage pointed at SHC’s own restic repository (an S3 bucket is never a vApp, and adoption is an edge operation). Making this edge SHC’s primary backup, in any documentation, anywhere.
10. Remaining unknowns, each with the command that settles it
Section titled “10. Remaining unknowns, each with the command that settles it”Ranked by what they would cost if the assumption is wrong.
| # | Unknown | Settles with | If wrong |
|---|---|---|---|
| 1 | Does a freshly occ user:add-ed account have a materialised DAV home before first login? (§4.2) | occ user:add --password-from-env probe; curl -u probe:… -X PROPFIND -H 'Depth: 0' …/dav/files/probe/ -w '%{http_code}'; expect 207 | the provision needs a --group (which triggers Filesystem::init) or a warm-up request; a 404 here means every first deposit fails |
| 2 | Does frappe.client.set_value satisfy a Single’s six reqd fields in one call, or does it need frappe.get_doc(...).save()? (§8.3) | bench --site <s> execute frappe.client.set_value --kwargs "{…all six…}" then read back | the configure job needs a different write primitive; the whole job is otherwise unchanged |
| 3 | Is the pinned image digest still the one the estate runs? (§0.3) | docker image inspect nextcloud@sha256:58bc7333… vs docker pull nextcloud:34.0.2-apache | the occ and remote.php reads need redoing against the pin; nothing here is version-sensitive, so this is diligence rather than risk |
| 4 | Does /remote.php/webdav (uid-free) behave as the authenticated principal’s root? (§3.1) | curl -u u:p -X PROPFIND -H 'Depth: 0' …/remote.php/webdav/ -w '%{http_code}' | only changes whether davPath can be made account-independent, a simplification, never a blocker |
| 5 | Does nextcloud_integration install cleanly on a v15.117 bench and register its scheduler events? | bench --site <s> install-app nextcloud_integration && bench --site <s> execute frappe.utils.scheduler.get_scheduler_events | the app’s four frappe imports are verified (§2.4) but the install has not been run; a v15 incompatibility elsewhere would surface here |
| 6 | Does the app’s PUT survive an SHC ingress in the public posture? (§2.3) | deposit once with vars.webdav.origin set to the public https origin | only decides whether the public posture is documented as supported; the in-fabric default is unaffected |
★ And the largest one, stated without hedging: none of this has been built or
run. The upstream reads are solid (the URL-builder defects in §2.2 were
reproduced, not inferred, and the occ semantics in §4.2 were read off the
image), but no socket has been rendered, no plug bound, and no archive
deposited. The first implementation pass will find things this document got
wrong.
11. Rulings owed
Section titled “11. Rulings owed”-
The deposit account: dedicated user, or the existing admin grant? (§4) The recommendation is a dedicated non-admin account, because unlike the calendar bridge’s user enumeration there is a scoped surface here (a plain user’s own DAV home), so taking admin authority would be taking more than the capability needs. The counter-argument is real and should be heard: a synthetic account lands inside the user set the mailbox reconciler and the calendar bridge both enumerate, and
nextcloud.socket.yamlalready refused a service user for exactly that reason. If the ruling goes the other way, the socket publishesadminUserand the plug declares alabel, and §4.1’s argument becomes a documented, accepted trade rather than a refusal. -
Does the teardown disable the deposit account? (§8.1) Reporting only is the safe default and matches the retained-cleanup channel’s whole purpose. Disabling stops future deposits from a detached consumer without destroying a single archive, and a shared account means a detach does not imply the account is unused. Recommendation: report only, and revisit when the per-consumer credential of §9.2 makes “this consumer’s access” a thing that can be revoked on its own.
-
Retention. (§2.5, §9.2) Nothing prunes. The three answers are: let the quota fill and fail loudly (honest, and the failure email is already wired); a Nextcloud-side sweep (new machinery, and it deletes backups); or state in the socket that retention is the operator’s, and print the quota at every bind. Recommendation: the third now, the first as its consequence, and never the second without an explicit ruling, because a job that deletes archives is exactly the class the estate keeps getting hurt by.
-
How many bench apps does the SHC frappe image carry, and who decides? (§8.4) This edge makes it three, one of them a dormant third-party pin at
0.0.1. That is a packaging policy question, not this socket’s to answer, but this socket is what forces it.
Not owed, because it is decided by measurement, not taste: the published
origin carries no port and no path (§2.2), and webdav.socket.yaml declares
service: nextcloud (§5.3). Both are constraints read off code, and a design
that contradicts either does not work rather than works differently.