dillard
138ee88486
Nextcloud's app id "occweb" is effectively unavailable for a new store listing: the original Adphi/occweb still owns that App Store slot (stale, v0.2.3), and el-choco/occweb_v2 has since published a same-lineage rewrite under its own id. Rather than fight over the "occweb" name, publish this fork under its own id, matching the <name> this app has always had: "Extended OCC Web". Renames every place the literal app id is used: info.xml <id> and the auto-generated navigation <route>, script()/style() registrations in templates/index.php, the TemplateResponse app name in OccController::index(), the /apps/... base URL in js/index.js, and the 'app' log context tag in DbController.php. The GitHub repo name and its <website>/<bugs>/<repository>/<screenshot> links are unaffected - those identify the repo, not the Nextcloud app. Docs (README, INSTALL-AIO.md, install.sh) updated to clone into and reference an "extended_occweb" directory, since Nextcloud requires the app folder name to match its id - a plain `git clone` of this repo no longer produces a correctly-named install directory on its own. Version bump to 0.4.0 given the scope (breaking change for anyone who already deployed under the old "occweb" id - requires disable+remove of the old app and a fresh enable under the new id, not an in-place upgrade).
155 lines
7.7 KiB
Markdown
155 lines
7.7 KiB
Markdown
# OCCWeb terminal (maintained fork)
|
|
|
|
### A web terminal for admins to launch Nextcloud's occ commands
|
|
|
|
|
|
|
|
## About this fork
|
|
|
|
The original [Adphi/occweb](https://github.com/Adphi/occweb) was marked deprecated by its
|
|
author and is unmaintained. This fork tracks [fanategorius/occweb](https://github.com/fanategorius/occweb),
|
|
which picked up compatibility maintenance where Adphi left off, and adds SQL query mode,
|
|
security hardening (admin checks, CSRF/confirmation flows, transactional batches), and PHP
|
|
8.1+ compatibility fixes on top.
|
|
|
|
### Credits
|
|
|
|
- [Adphi/occweb](https://github.com/Adphi/occweb) — original author/project.
|
|
- [fanategorius/occweb](https://github.com/fanategorius/occweb) — the actively maintained
|
|
fork this repo is based on and tracks.
|
|
- [Git-Usr123/occweb](https://github.com/Git-Usr123/occweb) — independent fork; the
|
|
`OC::$server->getConfig()` → `OC::$server->get(\OCP\IConfig::class)` fix in
|
|
`OccController.php` was spotted there and backported here.
|
|
|
|
**This tool is still not the right place for big/risky operations.** It has no support for
|
|
asynchronous or long-running tasks — every command runs synchronously inside a single PHP
|
|
web request, so anything that takes a while (`occ files:scan` on a large instance, a Nextcloud
|
|
major-version `occ upgrade`, `occ maintenance:mode --on` workflows) can time out mid-operation
|
|
with no way to recover cleanly. Use a real shell (SSH + `occ` directly, or the guest-agent/
|
|
console) for major upgrades and other long-running or high-blast-radius operations; reserve
|
|
this terminal for routine day-to-day occ/SQL admin tasks. [This issue](https://github.com/nextcloud/server/issues/16726)
|
|
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:
|
|
|
|
Nextcloud requires the app's directory name to match its id (`extended_occweb`), so
|
|
clone into that name explicitly rather than the repo's own name:
|
|
|
|
```bash
|
|
cd /var/www/nextcloud/apps
|
|
git clone https://github.com/dillardblom/occweb.git extended_occweb
|
|
bash extended_occweb/install.sh
|
|
```
|
|
|
|
`install.sh` removes the dev/CI-only files that don't belong in a running
|
|
install (`tests/`, `.travis.yml`, `phpunit*.xml`, `composer.json`,
|
|
`composer.lock`, `Makefile`), `chown -R`s the app directory to the web
|
|
server user, and runs `occ app:enable`. It assumes Nextcloud lives at
|
|
`/var/www/nextcloud` and the web server user is `www-data`; pass different
|
|
values as arguments if that's not the case:
|
|
|
|
```bash
|
|
bash extended_occweb/install.sh /path/to/nextcloud custom-web-user
|
|
```
|
|
|
|
`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.
|
|
|
|
Note: `install.sh` deletes files that are tracked in git. If you plan to
|
|
keep this install up to date with `git pull` instead of re-cloning, be
|
|
aware that a future upstream change to one of the removed files could make
|
|
a plain `git pull` refuse to merge — it will tell you so, and you can
|
|
`git checkout -- <file>` to recover it if that happens.
|
|
|
|
## SQL query mode
|
|
|
|
Type `sql` in the terminal to switch into SQL query mode and run raw SQL
|
|
statements directly against the Nextcloud database (admin only). Separate
|
|
statements with `;`. Use **Shift+Enter** to add a new line and **Enter** to
|
|
run the whole block in a single request — this matters for scripts like
|
|
`SET vars.x = 'value'; SELECT current_setting('vars.x');`, since every
|
|
statement in one submission runs on the same database connection/session.
|
|
Type `occ` to switch back to the normal occ-command mode.
|
|
|
|
⚠️ There is no undo for `DELETE`/`UPDATE` statements — double check what
|
|
you are about to run, ideally against a non-critical row/user first.
|
|
|
|
## ⚠️ Warnings ⚠️
|
|
|
|
- The application is not a real interactive terminal and does not support long running tasks.
|
|
So if your instance is pretty big, commands like `occ files:scan` will time out and fail.
|
|
- Do not use `occ maintenance:mode --on`, obvious...
|
|
- The `rename-user` SQL template is **best-effort only**: renaming a Nextcloud
|
|
username is not an officially supported operation. It updates the core
|
|
tables it knows about (`oc_users`, `oc_preferences`, `oc_group_user`,
|
|
`oc_group_admin`, `oc_ldap_user_mapping`, `oc_share`, `oc_mounts`,
|
|
`oc_storages`), but does **not** touch app-specific tables (Talk, Calendar,
|
|
Contacts, Mail, two-factor/WebAuthn, etc.). You must also manually rename
|
|
the user's data directory on disk (`data/<old> -> data/<new>`) with the web
|
|
server stopped or in maintenance mode, then run `occ files:scan --all`.
|
|
Back up the database first and test on a non-critical account.
|
|
|
|
## Deploying updates
|
|
|
|
After pulling/copying new code into `nextcloud/apps/extended_occweb/`, restart PHP so
|
|
the changes actually take effect. `occ app:disable`/`app:enable` is **not**
|
|
enough — it does not clear PHP's opcode cache, so a stale, cached version of
|
|
the code can keep running (routes silently 404ing is a typical symptom).
|
|
Restart the PHP process itself, for example:
|
|
|
|
```bash
|
|
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 extended_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.
|
|
|
|
## 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)
|