chore: document file locking problem in nextcloud with possible solution

Signed-off-by: Bert-Jan Fikse <bert-jan@whatwedo.ch>

README.md

@@ -28,3 +28,8 @@ This repository contains documentation, guides, and reference material.
   - [Enterprise App Integration with Keycloak](./ms-entra/enterprise-app-keycloak.md)
     Step-by-step instructions for creating an Enterprise Application in Microsoft Entra (Azure AD) as an identity provider for Keycloak.
 
+- **[Troubleshooting](./troubleshooting/)**
+  Encountered & solved problems.
+  - [Nextcloud File Locking](./troubleshooting/nextcloud-file-locking.md)
+    Preventing sync conflicts when multiple users edit the same file via the Nextcloud desktop client.
+

troubleshooting/nextcloud-file-locking.md

@@ -0,0 +1,26 @@
+# Nextcloud File Locking
+
+## Problem
+
+When two users open the same file simultaneously via the desktop sync client, both can write to it, resulting in sync conflicts.
+
+## Solution
+
+Two plugins work together to prevent this:
+
+- [**files_lock**](https://apps.nextcloud.com/apps/files_lock) — implements WebDAV locking (RFC 4918). When a user opens a file via the desktop client, a lock is acquired server-side. Other clients see the file as locked and cannot write to it.
+- [**notify_push**](https://apps.nextcloud.com/apps/notify_push) — pushes lock state changes to clients in real time, so they don't have to wait for the next poll cycle to discover a lock.
+
+## Installation
+
+```bash
+docker exec -u www-data <nextcloud-container> php occ app:install files_lock
+docker exec -u www-data <nextcloud-container> php occ app:install notify_push
+```
+
+Follow the `notify_push` setup guide to expose the push daemon via Traefik.
+
+## Limitations
+
+- Conflicts are theoretically still possible, but the chances are minimized.
+- Locks are per-session; if a client crashes without releasing the lock, the file may appear locked until the lock expires (default: 30 minutes, can be configured).