dillard
3b9fbf42a0
Rename the README title to Extended OCC Web (occ & SQL terminal), link the App Store listing, and describe the fork history in the past tense: the project no longer tracks fanategorius/occweb. Credits stay.
99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# 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 HEAD | 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/extended_occweb && \
|
|
tar -xf /tmp/occweb-deploy.tar -C /var/www/html/custom_apps/extended_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/extended_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 extended_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 extended_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 extended_occweb && \
|
|
docker exec nextcloud-aio-nextcloud rm -rf /var/www/html/custom_apps/extended_occweb"
|
|
```
|
|
|
|
## `max-version` policy
|
|
|
|
See the comment next to `<dependencies>` in `appinfo/info.xml`: it must always equal the
|
|
highest Nextcloud core version this app 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.
|
|
|
|
Before giving anyone access, read the Security section in the README: only
|
|
admins can use the app, and the database user should have limited rights.
|