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.
114 lines
5.4 KiB
Markdown
114 lines
5.4 KiB
Markdown
# ⚠️ Deprecated ⚠️ OCCWeb terminal
|
|
|
|
*Читать на [русском](README.ru.md).*
|
|
|
|
### 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](https://github.com/nextcloud/server/issues/16726) 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:
|
|
|
|
```bash
|
|
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 -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 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/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 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)
|