Add NC-version compatibility matrix to README

Live-tested against nc01 after its auto-update jumped to NC 34.0.4:

- Nextcloud's global jQuery has been deprecated since NC19 and is no
  longer reliably present/first-loaded on NC34 (other apps like
  serverinfo hit the same issue). occweb's index.js and the vendored
  jquery.terminal (term.js) both assume a global jQuery, so ship our
  own copy (js/jquery.js, 3.7.1 from code.jquery.com) and load it
  before them in templates/index.php. Fixes a hard "jQuery is not
  defined" crash that left the terminal blank (black screen).

- With that fixed, every ajax call started failing with HTTP 412
  "CSRF check failed": core only auto-attaches the requesttoken
  header to requests made through ITS OWN globally-loaded jQuery, and
  with occweb now vendoring a separate jQuery instance that no longer
  happens. A global $.ajaxSetup() call turned out unreliable (another
  app's later jQuery load can replace window.jQuery afterwards), so
  each of the three ajax calls (SQL query, initial completion list,
  occ command execution) now sets the requesttoken header explicitly
  via OC.requestToken.

Bump max-version to 34 - actually verified working on NC 34.0.4 now,
not inherited/guessed (see the policy comment in this same file).
Version bump to 0.3.5.

.gitignore

@@ -30,5 +30,8 @@ js/*.log
 .env
 *.local
 
+# Internal deploy notes (hostnames, paths) - never publish these
+notes/
+
 # Misc logs
 *.log

INSTALL-AIO.md

@@ -0,0 +1,95 @@
+# Installing/updating occweb on Nextcloud AIO (Docker)
+
+Nextcloud's official All-in-One (AIO) distribution runs core in its own container
+(`nextcloud-aio-nextcloud` by convention), so the generic [install instructions](README.md)
+(`git clone` straight into the server) don't apply as-is. This covers the differences.
+
+## Where the app belongs
+
+`/var/www/html/custom_apps/` inside the core container — **not** `/var/www/html/apps/`.
+AIO's `config.php` sets `apps_paths` with `apps/` as `writable: false` (managed by
+Nextcloud's own core/appstore sync, which can overwrite custom code placed there) and
+`custom_apps/` as `writable: true` — the intended location for third-party apps like
+this one.
+
+## Deploy/update procedure
+
+The AIO container has no working git access to GitHub, so deploy a tarball instead of
+`git clone`/`git pull` inside it:
+
+```bash
+# 1. On your machine: clean checkout of the branch/tag you want, dev files stripped
+STAGE=$(mktemp -d)
+git archive main | tar -x -C "$STAGE"
+rm -rf "$STAGE"/{tests,.travis.yml,phpunit.xml,phpunit.integration.xml,composer.json,composer.lock,Makefile}
+tar -C "$STAGE" -cf /tmp/occweb-deploy.tar .
+
+# 2. Copy it onto the Docker host, then into the container
+scp /tmp/occweb-deploy.tar <docker-host>:/tmp/occweb-deploy.tar
+ssh <docker-host> "docker cp /tmp/occweb-deploy.tar nextcloud-aio-nextcloud:/tmp/occweb-deploy.tar && \
+  docker exec nextcloud-aio-nextcloud sh -c 'mkdir -p /var/www/html/custom_apps/occweb && \
+  tar -xf /tmp/occweb-deploy.tar -C /var/www/html/custom_apps/occweb && rm /tmp/occweb-deploy.tar'"
+
+# 3. Fix ownership - tar preserves the source uid/gid, not www-data
+ssh <docker-host> "docker exec nextcloud-aio-nextcloud chown -R www-data:www-data /var/www/html/custom_apps/occweb"
+
+# 4. Fresh install only (skip when updating an already-enabled app):
+ssh <docker-host> "docker exec -u www-data nextcloud-aio-nextcloud php occ app:enable occweb"
+```
+
+> **Gotcha**: never copy a file into a container with `ssh host "docker exec container bash -c 'cat > file'"`
+> piped from local stdin — that produces an empty file. Always `scp` to the host, then
+> `docker cp` into the container, as above.
+
+## ⚠️ Critical after bumping `<version>` in `appinfo/info.xml`
+
+This step is **not optional** — skipping it doesn't just block occ commands, it can
+block **logging into the web UI entirely** (Nextcloud shows an upgrade screen to every
+user instead of the login page).
+
+Nextcloud tracks each app's installed version in the database (`installed_version` in
+`oc_appconfig`), separately from `<version>` in `info.xml`. If you replace files in place
+(instead of going through the app store or `occ upgrade`), those two fall out of sync,
+and Nextcloud puts the whole instance into a "needs upgrade" state until you sync it
+manually:
+
+```bash
+ssh <docker-host> "docker exec -u www-data nextcloud-aio-nextcloud php occ config:app:set occweb installed_version --value='X.Y.Z'"
+```
+
+(use the same `X.Y.Z` as the new `<version>`). Verify with `occ status` that
+`needsDbUpgrade: false` again.
+
+## Restart PHP-FPM after every deploy
+
+`occ app:disable`/`app:enable` does not clear PHP's opcache — an update can silently
+fail to take effect without a restart (routes 404ing is the typical symptom). Prefer a
+graceful reload over a hard restart (keeps in-flight requests alive):
+
+```bash
+ssh <docker-host> "docker exec nextcloud-aio-nextcloud ps aux | grep 'php-fpm: master'"   # find the PID
+ssh <docker-host> "docker exec nextcloud-aio-nextcloud kill -USR2 <master-pid>"
+```
+
+`supervisorctl` won't work directly inside this container (its socket isn't at the
+default path) — hence the manual PID lookup.
+
+## Removing the app
+
+```bash
+ssh <docker-host> "docker exec -u www-data nextcloud-aio-nextcloud php occ app:disable occweb && \
+  docker exec nextcloud-aio-nextcloud rm -rf /var/www/html/custom_apps/occweb"
+```
+
+## `max-version` policy
+
+See the comment next to `<dependencies>` in `appinfo/info.xml`: it must always equal the
+highest Nextcloud core version this fork has actually been verified against — never a
+value inherited from upstream, and never a guess ahead of what's been tested. Test
+against the next major's beta ahead of time and bump it before that major goes final,
+rather than reacting after the fact.
+
+## SQL query mode
+
+Type `sql` in the OCCWeb terminal to run raw SQL directly against the Nextcloud
+database. Separate statements with `;`, use Shift+Enter for a new line and Enter to run.

README.md

@@ -2,7 +2,7 @@
 
 ### A web terminal for admins to launch Nextcloud's occ commands
 
-![occweb](https://github.com/Adphi/OCCWeb/raw/main/appinfo/screenshot.png)
+![occweb](https://github.com/dillardblom/occweb/raw/main/appinfo/screenshot.png)
 
 ## About this fork
 
@@ -33,12 +33,15 @@ has background on why Nextcloud has no native async support for occ tasks.
 
 ## Install
 
+Running Nextcloud AIO (Docker)? See [INSTALL-AIO.md](INSTALL-AIO.md) instead — the app
+path and deploy steps differ from the generic instructions below.
+
 No build step required (plain PHP + vanilla JS). Clone straight into the
 target server's `apps/` directory and run the install script:
 
 ```bash
 cd /var/www/nextcloud/apps
-git clone https://github.com/fanategorius/occweb.git
+git clone https://github.com/dillardblom/occweb.git
 bash occweb/install.sh
 ```
 
@@ -128,5 +131,21 @@ sudo -u www-data php /var/www/nextcloud/occ config:app:set occweb installed_vers
 This does not apply on a fresh `occ app:enable` install — that command sets
 `installed_version` correctly on its own.
 
+## Compatibility matrix
+
+`max-version` in `appinfo/info.xml` only ever reflects the highest version we've actually
+tested (see the policy comment right above it) - this table is the actual history of what
+was verified, so a rollback target is obvious if a newer major causes problems.
+
+| occweb version | Tag | NC version tested | Result |
+|---|---|---|---|
+| 0.3.4 | `v0.3.4` | 33.0.8 | ✅ Verified (nc01, 2026-09-25) |
+| 0.3.4 | `v0.3.4` | 34.0.4 | ❌ Blank terminal - global jQuery gone on NC34 (`jQuery is not defined`), then a 412 "CSRF check failed" on every ajax call once jQuery was vendored. Fixed in 0.3.5. |
+| 0.3.5 | `v0.3.5-nc34` | 34.0.4 | ✅ Verified (nc01, 2026-09-26) - vendors its own jQuery + sends the CSRF `requesttoken` header explicitly on every ajax call |
+| 0.3.5 | `v0.3.5-nc34` | 33.0.8 | ⚠️ Believed compatible (the 0.3.5 change is additive-only, nothing removed that NC30-33 depended on) but not re-verified - nc01 no longer runs NC33 to test against |
+
+If a future major breaks something, `git checkout v0.3.4` is the last version confirmed
+working on NC33 and older.
+
 ## TODOs:
 See [open issues](https://github.com/dillardblom/occweb/issues)

appinfo/info.xml

@@ -5,7 +5,7 @@
     <name>Extended OCC Web</name>
     <summary>OCC Commands in a web terminal</summary>
     <description><![CDATA[Run OCC Commands in a web terminal]]></description>
-    <version>0.3.4</version>
+    <version>0.3.5</version>
     <licence>agpl</licence>
     <author mail="dillard.blom@ensembia.com" >Dillard Blom</author>
     <namespace>OCCWeb</namespace>
@@ -15,7 +15,12 @@
     <repository>https://github.com/dillardblom/occweb</repository>
     <screenshot>https://github.com/dillardblom/occweb/raw/main/appinfo/screenshot.png</screenshot>
     <dependencies>
-        <nextcloud min-version="30" max-version="33"/>
+        <!-- max-version must equal the highest NC core version this fork has
+             actually been verified on - never a value inherited from upstream
+             or guessed ahead. Test against the next major's beta and bump
+             this BEFORE it goes final, so occ:upgrade never has to fall back
+             to auto-disabling the app. -->
+        <nextcloud min-version="30" max-version="34"/>
     </dependencies>
     <navigations>
         <navigation role="admin">

composer.json

@@ -6,6 +6,10 @@
     "authors": [
         {
             "name": "Adphi"
+        },
+        {
+            "name": "Dillard Blom",
+            "email": "dillard.blom@ensembia.com"
         }
     ],
     "require": {},

install.sh

@@ -3,7 +3,7 @@
 # Post-clone install script for occweb.
 #
 # Usage (from nextcloud/apps/):
-#   git clone https://github.com/fanategorius/occweb.git
+#   git clone https://github.com/dillardblom/occweb.git
 #   bash occweb/install.sh [nextcloud-root] [web-user]
 #
 # Defaults: nextcloud-root=/var/www/nextcloud, web-user=www-data

js/index.js

@@ -1,6 +1,13 @@
 (function (OC, window, $, undefined) {
   'use strict';
   $(function() {
+    // Nextcloud core only auto-attaches the CSRF requesttoken header to ajax
+    // calls made through its own globally-loaded jQuery. Since NC34 that
+    // global jQuery is no longer guaranteed to be the one still active by
+    // the time our own calls fire (other apps loading their own jQuery can
+    // replace window.jQuery afterwards - see js/jquery.js), ajaxSetup() here
+    // isn't reliable; every $.ajax() call below sets the header explicitly.
+
     function scrollToBottom(){
       var html = $('html');
       html.scrollTop(html.prop('scrollHeight'));
@@ -287,6 +294,7 @@
         type: 'POST',
         contentType: 'application/json',
         timeout: SQL_REQUEST_TIMEOUT_MS,
+        headers: { requesttoken: OC.requestToken },
         data: JSON.stringify({ sql: sql, confirm: !!confirmed })
       }).done(function (response) {
         if (response && response.requiresConfirmation) {
@@ -319,7 +327,7 @@
       });
     }
 
-    $.get(baseUrl + '/cmd', function(response){
+    $.ajax({ url: baseUrl + '/cmd', headers: { requesttoken: OC.requestToken } }).done(function(response){
       $('#app-content').terminal(function(command, term) {
         if (mode === 'sql') {
           var trimmed = command.trim();
@@ -375,6 +383,7 @@
             url: baseUrl + '/cmd',
             type: 'POST',
             contentType: 'application/json',
+            headers: { requesttoken: OC.requestToken },
             data: JSON.stringify(occCommand)
           }).done(function (response) {
             term.echo('\n' + response).resume();

templates/index.php

@@ -1,4 +1,9 @@
 <?php
+// Nextcloud's global jQuery has been deprecated since NC19 and is no longer
+// reliably present on NC34+ (see e.g. serverinfo needing to bundle its own) -
+// term.js (jquery.terminal) and index.js both require jQuery to be loaded
+// first, so ship and load our own copy rather than relying on core.
+script('occweb', 'jquery');
 script('occweb', 'index');
 script('occweb', 'term');
 script('occweb', 'unix_formatting');