Document install-on-a-new-server steps and installed_version sync gotcha

README.md

@@ -14,7 +14,27 @@ As nextcloudd has no native support for asynchronous operations, due to the use
 
 ## Install
 
-Place this app in **nextcloud/apps/**
+No build step required (plain PHP + vanilla JS). Clone straight into the
+target server's `apps/` directory and enable it:
+
+```bash
+cd /var/www/nextcloud/apps
+git clone https://github.com/fanategorius/occweb.git
+chown -R www-data:www-data occweb   # match your web server user
+sudo -u www-data php /var/www/nextcloud/occ app:enable occweb
+```
+
+`occ app:enable` takes care of registering the app's version correctly, so
+none of the "Deploying updates" caveats below apply to a fresh install —
+they only matter once the app is already enabled and you're updating it in
+place.
+
+Before installing, check your Nextcloud version against the range in
+`appinfo/info.xml` (`dependencies/nextcloud`, currently `min-version`/
+`max-version`) — `occ app:enable` refuses to enable an app outside that
+range. If you're offline or without GitHub access, build a tarball instead
+with `make dist` (uses the included Makefile) and extract it into `apps/`
+on the target server.
 
 ## SQL query mode
 
@@ -48,5 +68,23 @@ sudo systemctl restart php8.3-fpm   # adjust to your installed PHP version
 sudo systemctl restart apache2      # if PHP runs as an Apache module instead
 ```
 
+### If you bump the `<version>` in `appinfo/info.xml`
+
+Nextcloud tracks each app's installed version in its database (`installed_version`
+in `oc_appconfig`) separately from the `<version>` in `info.xml`. If you edit
+files in place (copy/`git pull`) instead of going through the app store or
+`occ upgrade`, those two get out of sync — Nextcloud then treats the whole
+instance as "needs upgrade" and blocks most `occ` commands behind the
+CLI-upgrade wizard, even though nothing about Nextcloud core actually
+changed. After bumping the version, sync it manually:
+
+```bash
+sudo -u www-data php /var/www/nextcloud/occ config:app:set occweb installed_version --value="X.Y.Z"
+```
+
+(use the same `X.Y.Z` as the new `<version>`), then restart PHP as above.
+This does not apply on a fresh `occ app:enable` install — that command sets
+`installed_version` correctly on its own.
+
 ## TODOs:
 See [open issues](https://github.com/Adphi/occweb/issues)

README.ru.md

@@ -22,7 +22,26 @@ websockets), а отсутствие настоящей асинхронност
 
 ## Установка
 
-Поместите это приложение в **nextcloud/apps/**
+Сборка не нужна (чистый PHP + vanilla JS). Клонируйте прямо в `apps/`
+целевого сервера и включите приложение:
+
+```bash
+cd /var/www/nextcloud/apps
+git clone https://github.com/fanategorius/occweb.git
+chown -R www-data:www-data occweb   # укажите вашего пользователя веб-сервера
+sudo -u www-data php /var/www/nextcloud/occ app:enable occweb
+```
+
+`occ app:enable` сам корректно проставит версию приложения в базе, поэтому
+оговорки из раздела «Обновление кода на сервере» ниже к свежей установке не
+относятся — они актуальны только когда приложение уже включено и вы
+обновляете его на месте.
+
+Перед установкой сверьте версию вашего Nextcloud с диапазоном в
+`appinfo/info.xml` (`dependencies/nextcloud`, `min-version`/`max-version`)
+— `occ app:enable` откажется включать приложение вне этого диапазона. Если
+нет доступа к GitHub — соберите tar.gz через `make dist` (есть готовый
+Makefile) и распакуйте его в `apps/` на целевом сервере.
 
 ## Режим SQL-запросов
 
@@ -61,5 +80,23 @@ sudo systemctl restart php8.3-fpm   # укажите свою версию PHP
 sudo systemctl restart apache2      # если PHP работает как модуль Apache
 ```
 
+### Если меняете `<version>` в `appinfo/info.xml`
+
+Nextcloud хранит установленную версию каждого приложения в базе
+(`installed_version` в `oc_appconfig`) отдельно от `<version>` в
+`info.xml`. Если вы правите файлы на месте (копированием/`git pull`), а не
+через App Store или `occ upgrade`, эти два значения расходятся — и
+Nextcloud считает, что «инстансу нужен апгрейд», блокируя большинство
+`occ`-команд за CLI-визардом обновления, хотя само ядро Nextcloud никак не
+менялось. После бампа версии синхронизируйте её вручную:
+
+```bash
+sudo -u www-data php /var/www/nextcloud/occ config:app:set occweb installed_version --value="X.Y.Z"
+```
+
+(то же значение `X.Y.Z`, что и в новом `<version>`), затем перезапустите
+PHP, как описано выше. На свежую установку через `occ app:enable` это не
+распространяется — там версия проставляется корректно автоматически.
+
 ## Планы (TODO):
 См. [открытые issues](https://github.com/Adphi/occweb/issues)