dillard
422748cace
Independent Codex review of the app-id rename found real gaps our own
review missed:
- Makefile: app_name was derived from the checkout directory's own
basename, not the app id in appinfo/info.xml. Our actual working
checkout is still named "occweb" (matches the repo name), so
building from it would have produced an "occweb"-named/rooted
archive under the new "extended_occweb" id. Fixed by deriving
app_name from info.xml via xpath (same technique already used for
VERSION), and added an ensure-app-name-symlink step so the
Makefile's inherited "../$(app_name)" references (used throughout
the source/appstore tar exclude patterns) keep resolving correctly
regardless of what the checkout directory is actually named.
Verified end to end: `make appstore` now produces
extended_occweb.tar.gz with extended_occweb/ as its single top-level
folder, matching the App Store's stated requirement.
- Makefile: sign target had "occweb" hardcoded into both the
certificate path and the archive filename - broken independent of
the app_name fix above. Now derived from the same variables.
- Makefile: version target pushed the release tag to the "origin"
remote, which in this repo is the stale upstream
(fanategorius/occweb), not somewhere we want to push. Changed to
"fork" (dillardblom/occweb), matching how every tag has actually
been pushed this whole session.
- INSTALL-AIO.md / notes/deploy-nc01.md: the deploy snippet did
`git archive main` unconditionally, silently deploying the main
branch even if an operator had checked out a specific tag or
maintenance branch as instructed elsewhere. Changed to `git archive
HEAD`.
- README.md: the compatibility matrix's rollback advice
("git checkout v0.3.4") doesn't actually work as a rollback anymore
post-rename - that tag still declares the old occweb id, so checking
it out under an extended_occweb-named install just breaks. Added a
caveat explaining what a real rollback requires; full migration docs
are still deferred to when a test instance exists (tracked
separately, not written up here).
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 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 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.
|