Merge pull request 'feat(deploy): rclone WebDAV mount (docker compose) + smoke + docs (#54)' (#59) from feat/rclone-webdav#54 into main

.env.example

@@ -22,6 +22,12 @@ ONLYOFFICE_PROJECT_ID=33
 
 # oo mails uses ONLYOFFICE_URL/USER/PASS above (Workspace Mail addon).
 
+# deploy/docker-compose.rclone-webdav.yml — rclone FUSE mount of the oo-webdav
+# sidecar. Reuses ONLYOFFICE_USER and accepts ONLYOFFICE_PASSWORD (alias
+# ONLYOFFICE_PASS). Set ONLYOFFICE_WEBDAV_URL only if the sidecar is not on
+# the default docker bridge address. See docs/rclone-webdav.md.
+# ONLYOFFICE_WEBDAV_URL=http://172.17.0.1:8098/webdav
+
 # cmd/office TUI — optional Document Server for DOCX→HTML preview:
 # ONLYOFFICE_DOCS_URL=https://docs.example.com
 # ONLYOFFICE_DOCS_SECRET=

deploy/docker-compose.rclone-webdav.yml

@@ -0,0 +1,70 @@
+# rclone WebDAV mount of the oo-webdav sidecar (OnlyOffice Documents).
+#
+# The sidecar publishes the portal's WebDAV tree on the docker bridge
+# (http://172.17.0.1:8098, prefix /webdav). rclone mounts it inside this
+# container as a normal filesystem.
+#
+# Credentials are OnlyOffice portal credentials (the same the `oo` CLI uses).
+# Export them before `docker compose up`, e.g.
+#   set -a; . .secrets/oo.env; set +a
+# or copy .env.example to .env and fill it. Only names live in git.
+#
+#   docker compose -f deploy/docker-compose.rclone-webdav.yml up -d
+#   docker exec rclone-webdav ls /mnt/onlyoffice
+#   docker compose -f deploy/docker-compose.rclone-webdav.yml down
+#
+# The mount point is the named volume `onlyoffice-mnt`; join it from another
+# container with `external_volumes` to read the tree without the API.
+name: rclone-webdav
+
+services:
+  rclone-webdav:
+    image: rclone/rclone:latest
+    container_name: rclone-webdav
+    restart: unless-stopped
+    # rclone mount needs FUSE. The remote is defined on the fly via flags for
+    # the mount; the same credentials are written to an rclone config so that
+    # `docker exec rclone-webdav rclone ls webdav:` works without flags.
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - |
+        set -eu
+        : "$${ONLYOFFICE_USER:?ONLYOFFICE_USER is required}"
+        : "$${ONLYOFFICE_PASSWORD:?ONLYOFFICE_PASSWORD is required}"
+        obscured=$$(rclone obscure "$${ONLYOFFICE_PASSWORD}")
+        mkdir -p /config/rclone
+        cat > /config/rclone/rclone.conf <<EOF
+        [webdav]
+        type = webdav
+        url = $${ONLYOFFICE_WEBDAV_URL}
+        vendor = other
+        user = $${ONLYOFFICE_USER}
+        pass = $${obscured}
+        EOF
+        exec rclone mount :webdav: /mnt/onlyoffice \
+          --webdav-url "$${ONLYOFFICE_WEBDAV_URL}" \
+          --webdav-user "$${ONLYOFFICE_USER}" \
+          --webdav-pass "$${obscured}" \
+          --vfs-cache-mode writes \
+          --cache-dir /cache \
+          --dir-cache-time 1m \
+          --allow-other \
+          --allow-non-empty
+    environment:
+      ONLYOFFICE_USER: ${ONLYOFFICE_USER:?ONLYOFFICE_USER is required}
+      ONLYOFFICE_PASSWORD: ${ONLYOFFICE_PASSWORD:-${ONLYOFFICE_PASS:?ONLYOFFICE_PASSWORD is required}}
+      ONLYOFFICE_WEBDAV_URL: ${ONLYOFFICE_WEBDAV_URL:-http://172.17.0.1:8098/webdav}
+    cap_add:
+      - SYS_ADMIN
+    devices:
+      - /dev/fuse
+    # Ubuntu hosts run AppArmor; FUSE mounts need it unconfined.
+    security_opt:
+      - apparmor:unconfined
+    volumes:
+      - onlyoffice-mnt:/mnt/onlyoffice
+      - rclone-cache:/cache
+
+volumes:
+  onlyoffice-mnt:
+  rclone-cache:

docs/rclone-webdav.md

@@ -0,0 +1,109 @@
+---
+type: reference
+status: current
+related:
+  - deploy/docker-compose.rclone-webdav.yml
+  - docs/unified-file-client.md
+---
+
+# rclone WebDAV mount — OnlyOffice Documents как файловая ФС
+
+`deploy/docker-compose.rclone-webdav.yml` монтирует WebDAV-дерево OnlyOffice
+через `rclone`. Не systemd, только compose. Контейнер — `rclone-webdav`.
+
+## Что монтируется
+
+- Источник — сайдкар `oo-webdav` (`ghcr.io/eslider/oo-webdav`).
+- Адрес — `http://172.17.0.1:8098`, префикс `/webdav`.
+- Basic-auth — креды портала OnlyOffice (те же, что у `oo`).
+- Корень — `Dokumente der Projekte/…` (папка `Fibu EDL` внутри).
+
+## Конфиг
+
+- Образ — `rclone/rclone`.
+- Remote — on-the-fly `:webdav:` плюс флаги `--webdav-url`, `--webdav-user`,
+  `--webdav-pass`.
+- На старте контейнер пишет `/config/rclone/rclone.conf` (`[webdav]`), чтобы
+  `rclone ls webdav:` внутри контейнера работал без флагов.
+- `ONLYOFFICE_PASSWORD` — plain; rclone сам зовёт `rclone obscure`.
+- Флаги mount: `--vfs-cache-mode writes`, `--cache-dir /cache`,
+  `--dir-cache-time 1m`, `--allow-other`, `--allow-non-empty`.
+- FUSE: `cap_add: [SYS_ADMIN]`, `devices: [/dev/fuse]`,
+  `security_opt: apparmor:unconfined`.
+- Тома: `onlyoffice-mnt` → `/mnt/onlyoffice`, `rclone-cache` → `/cache`.
+
+### env (только имена)
+
+| Переменная | Значение |
+|------------|----------|
+| `ONLYOFFICE_USER` | пользователь портала |
+| `ONLYOFFICE_PASSWORD` | пароль портала (алиас `ONLYOFFICE_PASS`) |
+| `ONLYOFFICE_WEBDAV_URL` | по умолчанию `http://172.17.0.1:8098/webdav` |
+
+## Команды
+
+```bash
+# креды (или .env рядом с compose)
+set -a; . .secrets/oo.env; set +a
+
+docker compose -f deploy/docker-compose.rclone-webdav.yml up -d
+docker compose -f deploy/docker-compose.rclone-webdav.yml ps
+docker compose -f deploy/docker-compose.rclone-webdav.yml down
+
+# дерево
+docker exec rclone-webdav rclone ls webdav:
+docker exec rclone-webdav rclone lsf webdav:
+
+# содержимое точки монтирования
+docker exec rclone-webdav ls /mnt/onlyoffice
+
+# чтение/запись как обычная ФС
+docker exec rclone-webdav cat "/mnt/onlyoffice/Meine Dokumente/x.txt"
+```
+
+## Smoke (проверено 2026-09-16)
+
+```text
+$ docker exec rclone-webdav rclone ls webdav:
+  5357109 Meine Dokumente/ONLYOFFICE-Audiobeispiel.mp3
+    44805 Meine Dokumente/ONLYOFFICE-Beispiel-Tabellenblatt.xlsx
+    58988 Meine Dokumente/ONLYOFFICE-Beispieldokument.docx
+  ...
+
+$ TS=20260916-212459
+$ docker exec rclone-webdav sh -c "printf 'rclone-webdav round-trip $TS\n' \
+    > '/mnt/onlyoffice/Meine Dokumente/rclone-smoke-$TS/hello.txt'"
+# ждём появления на сервере (host HTTP, мимо монтирования):
+GET /webdav/Meine%20Dokumente/rclone-smoke-$TS/hello.txt -> 200 (через 7s)
+server bytes: rclone-webdav round-trip 20260916-212459
+# читаем обратно через монтирование:
+mount read: rclone-webdav round-trip 20260916-212459
+MATCH: yes
+
+$ docker exec rclone-webdav rm -f \
+    "/mnt/onlyoffice/Meine Dokumente/rclone-smoke-$TS/hello.txt"
+GET /webdav/Meine%20Dokumente/rclone-smoke-$TS/hello.txt -> 404 (через 1s)
+
+# пустой каталог: rmdir через монтирование на сервер не доходит,
+# удаляем напрямую:
+$ docker exec rclone-webdav rclone rmdir "webdav:Meine Dokumente/rclone-smoke-$TS"
+PROPFIND rclone-smoke-20260916-212459/ -> 404
+no rclone-smoke leftovers
+```
+
+Вывод: запись → чтение → удаление файла подтверждены. Файл удалён.
+
+## Ограничения
+
+- Нужен FUSE: `SYS_ADMIN` + `/dev/fuse`. На хосте без FUSE не поедет.
+- Сайдкар слушает docker-bridge `172.17.0.1:8098`, публично не выставлен.
+  Только localhost/локальные контейнеры.
+- Запись идёт через VFS write-back (по умолчанию ~5s). Перед проверкой
+  «файл на сервере» опрашивать сервер, не доверять сразу после `write`.
+- `rmdir` через монтирование НЕ доходит до `oo-webdav` (пустой каталог
+  остаётся на сервере). Удалять каталоги напрямую:
+  `rclone rmdir webdav:<path>` или `rclone purge webdav:<path>`.
+- VFS-кэш растёт в томе `rclone-cache`; ограничить `--vfs-cache-max-size`.
+- Блокировок между редактором OnlyOffice и монтированием нет. Не редактировать
+  один и тот же файл одновременно.
+- Данные не шифруются на диске хоста в `rclone-cache` (том Docker).