Egor Bugaev
9e15c3b96c
- New 'rename-user' template (templates / template rename-user <old> <new>): best-effort uid rename across core tables (oc_users, oc_preferences, oc_group_user, oc_group_admin, oc_ldap_user_mapping, oc_share, oc_mounts, oc_storages). Explicitly NOT a supported Nextcloud operation - the generated script carries an in-line warning (as leading SQL comments) that app-specific tables (Talk, Calendar, Contacts, Mail, 2FA/WebAuthn...) are not covered and that the data directory must be renamed on disk manually, followed by occ files:scan --all. Documented the same caveat in both READMEs. - Hardened the round-2 transaction wrapping: beginTransaction()/commit()/ rollBack() are now wrapped in try/catch. PostgreSQL (our backend) has fully transactional DDL so this wasn't actually broken here, but Nextcloud also supports MySQL/MariaDB via the same IDBConnection, where DDL implicitly commits - on that backend a DDL statement in the batch would make a later commit()/rollBack() throw 'no active transaction' and previously that exception was unhandled (HTTP 500 instead of a clean JSON response). Now: if rollBack() itself fails after an error, we report rollbackFailed+warning instead of falsely claiming rolledBack, since earlier statements in that batch may already be permanently applied. If commit() fails with nothing to commit (already auto-committed), that's logged only, since the effects are already durably persisted.
⚠️ Deprecated ⚠️ OCCWeb terminal
Читать на русском.
A web terminal for admins to launch Nextcloud's occ commands
⚠️ Deprecated ⚠️
As nextcloudd has no native support for asynchronous operations, due to the use of php, this aplication is deprecated, and will no longer support the Nextcloud' future versions (19+). I did not find a way to implemement true support for interactive and long running occ tasks in a web terminal whitout introducing addtional dependencies (through websockets, for example), the lack of true asynchronous occ operations can lead to serious alterations of voluminous instances. This issue may give some hints on why I decided to not support this application anymore.
Install
No build step required (plain PHP + vanilla JS). Clone straight into the
target server's apps/ directory and run the install script:
cd /var/www/nextcloud/apps
git clone https://github.com/fanategorius/occweb.git
bash 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 -Rs 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 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:scanwill time out and fail. - Do not use
occ maintenance:mode --on, obvious... - The
rename-userSQL 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 runocc 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/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:
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:
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