mesh-catalog/modules/nextcloud-client/README.md

nextcloud-client

The Nextcloud desktop sync client on the workstations, as a module (novox/hq ADR 0208). It requires x11-display, so it is assigned only where a display server is held on the same machine.

Owns

what	where
the client	package nextcloud-client, from the official repositories

Nothing else. It holds no seat, makes no contribution and writes no file.

• No AUR, no vendored copy. Both workstations run the official package (extra), installed explicitly. ADR 0205 does not apply.
• The account configuration stays the operator's. ~/.config/Nextcloud/nextcloud.cfg is the client's own file, and the client rewrites it. That makes it found in ADR 0182's terms: the module never declares, reads into or writes it. The tools only read it. The accounts, the sync folders, the server and the credentials are set in the client.

How it starts: the client's own autostart entry, and nothing else

One process has one starter (the rule picom states for the desktop modules). The client's starter is its own XDG autostart entry, ~/.config/autostart/Nextcloud.desktop (nextcloud --background).

• The client writes that entry itself while its setting Launch on system startup is ticked, and removes it when the setting is unticked.
• The session runs every XDG autostart entry once at login: the i3 module's dex --autostart --environment i3.
• The package ships no /etc/xdg/autostart entry.

Why not a contribution to node-display-session or the xinitrc slot: the client would still write its own entry whenever the setting is ticked, and the session would start it twice. The module cannot own the entry either, because the client rewrites it on every start. Declaring that file would make two writers of one file. So the module adds no start, and nextcloud_check holds the rule instead: it names any second start it finds.

• Excluded: the window manager's exec … nextcloud (the i3 module's configuration dropped it), and the package's user unit com.nextcloud.desktopclient.nextcloud.service, which stays disabled. User-scoped units are not declarable yet (mesh-host #72).
• One caveat: dex ignores the entry's X-GNOME-Autostart-Delay=10, so the client starts with the session. It retries its connection by itself, so that is harmless.

Tools

They are served by the node's runtime as the operator account (ADR 0175), and are read-only except restart. No answer carries the server's address, the account's user ids or a credential.

• nextcloud.cfg is read only to learn what to hide.
• The log tools replace the server's host with <server> and the user ids with <account>.
• Anything shaped like a credential (Authorization:, token=, password=, a cookie) becomes <hidden>.

tool	does
nextcloud_status (r)	whether the client runs: pid, since, and the scope or unit it runs in the installed version, and what starts it at login each account by display name and auth type, with each sync folder: local path (~/…), remote path, paused, virtual files, journal present each folder's last sync run: started, finished or still running, items, errors, the first ten failing files the latest warnings and worse in the client's log
nextcloud_log (r)	the last lines (default 100, at most 2000) of the client's log (source: client). The log rotates every two hours, and older gzipped files are read until the count is reached. problems: true keeps warnings and worse. source: sync gives the sync runs' log. Answers are capped at 256 KiB
nextcloud_restart (a)	asks the client to end (SIGTERM), forces it after 6 s, and starts nextcloud --background in the operator's session. The start is a transient user unit mesh-nextcloud-client, so it outlives the tools runtime. Answers the pids. Refused plainly when nobody is logged in to the desktop
nextcloud_check (r)	the package is installed exactly one start: the entry is present and enabled, and dex is installed no window-manager exec and no enabled user unit one client runs in a desktop session an account exists, its folders exist with a journal, and none is paused Each finding says what to do

Where the tools read:

• The client's settings are read from ~/.config/Nextcloud/nextcloud.cfg.
• Its log is read from ~/.config/Nextcloud/logs/*_nextcloud.log*.
• Each folder's sync runs are read from the *_sync.log whose first line is that folder's path. That file is in ~/.local/share/Nextcloud/, or in ~/.config/Nextcloud/ for older clients, and the newest one wins.

The tools find the session's DISPLAY and XAUTHORITY from the window manager's own environment, as clipmenu and screen-lock do. Every command has a timeout and capped output. Everything runs through an injected runner and a fake root in the tests.

What changes when it is assigned

	g14	shanks
package	none: nextcloud-client 34.0.4 is installed, explicitly, from extra	the same
start	none: dex starts it from the client's own entry (--background, in the login session's scope)	none on disk. The client running now came from the predecessor's window-manager line (nextcloud, a child of i3, since the session of 2026-10-04 16:00). That session began before the i3 module dropped the line and installed dex, so the next login is the first that starts it from its entry
settings	one account, one folder (~/Nextcloud/, whole server), not paused, no virtual files; Launch on system startup on	the same

The workstations are already in the state this module describes.

Migration (ADR 0182)

Nothing is required on either machine.

• shanks: log out and in once, or run nextcloud_restart, and the client runs from its one start. nextcloud_check then answers ok.
• Optional, both: the client has kept a nextcloud.cfg.backup_<date>_<version> from every upgrade since 2023 (about twenty on each machine). It also keeps a sync log that it no longer writes, at ~/.config/Nextcloud/Nextcloud_sync.log, from 2024 on g14 and 2023 on shanks. They are the operator's to delete. The module leaves them.

Leaves as found

• ~/.config/Nextcloud/: the settings, their backups, cookies0.db, sync-exclude.lst, the logs.
• ~/.local/share/Nextcloud/: the sync runs' log.
• ~/.config/autostart/Nextcloud.desktop, the client's.
• Every sync folder and its .sync_*.db journal.

Relies on

• i3's dex line for the start. Nothing in the mesh says so yet: XDG autostart has no seat, and a module without a seat or contribution has no way to depend on another module. Assigned without i3, the client is installed and does not start. nextcloud_check says so.
• A display server on the same machine (x11-display, ADR 0208 §3). Under sway the client runs on Wayland as well. A Wayland twin then requires wayland-display.