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).
96 lines
4.4 KiB
Markdown
96 lines
4.4 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 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/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 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.
|