Replace INSTALL-AIO.md with a generic, English, host-agnostic version
The previous version was in Dutch and hardcoded internal deploy details (hostname alias, personal local path, private Gitea mirror domain) that had no business being in a public repo. Replaced with a generic version using <docker-host> placeholders; the internal nc01-specific copy now lives at notes/deploy-nc01.md, which is gitignored and stays local-only. Not rewriting prior history for this (confirmed with user: nothing credential-level was exposed, just a hostname alias and a path).
This commit is contained in:
@@ -30,5 +30,8 @@ js/*.log
|
||||
.env
|
||||
*.local
|
||||
|
||||
# Internal deploy notes (hostnames, paths) - never publish these
|
||||
notes/
|
||||
|
||||
# Misc logs
|
||||
*.log
|
||||
|
||||
+56
-50
@@ -1,89 +1,95 @@
|
||||
# occweb installeren/updaten in Nextcloud AIO
|
||||
# Installing/updating occweb on Nextcloud AIO (Docker)
|
||||
|
||||
Fork van de originele OCCWeb-app (upstream `fanategorius/occweb` toont weinig activiteit;
|
||||
laatste bekende versie daar is nog altijd 0.3.3, geen tags/releases). Deze fork
|
||||
(`dillardblom/occweb`, gespiegeld op `git.ensembia.net/Ensembia/occweb`) is de actief
|
||||
onderhouden versie en draait op nc01.
|
||||
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.
|
||||
|
||||
**Versie**: zie `<version>` in `appinfo/info.xml`.
|
||||
## Where the app belongs
|
||||
|
||||
## Waar de app hoort
|
||||
`/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.
|
||||
|
||||
`/var/www/html/custom_apps/occweb` — **niet** `/var/www/html/apps/occweb`. AIO's
|
||||
`config.php` heeft `apps_paths` met `apps/` op `writable:false` (beheerd door
|
||||
Nextcloud's core-appstore-sync, kan custom code overschrijven) en `custom_apps/` op
|
||||
`writable:true` (de bedoelde plek voor third-party apps als deze).
|
||||
## Deploy/update procedure
|
||||
|
||||
## Deploy/update-procedure
|
||||
|
||||
De container heeft geen (werkende) git-toegang naar GitHub; deploy lokaal een tarball
|
||||
i.p.v. `git clone`/`git pull` in de container.
|
||||
The AIO container has no working git access to GitHub, so deploy a tarball instead of
|
||||
`git clone`/`git pull` inside it:
|
||||
|
||||
```bash
|
||||
# 1. Lokaal: clean checkout van main (dev-bestanden eruit) als tar
|
||||
cd ~/Next/Documents/Development/Nextcloud/occweb
|
||||
# 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. Naar nc01, in de container uitpakken over de bestaande app
|
||||
scp /tmp/occweb-deploy.tar nc01:/tmp/occweb-deploy.tar
|
||||
ssh nc01 "docker cp /tmp/occweb-deploy.tar nextcloud-aio-nextcloud:/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/occweb && \
|
||||
tar -xf /tmp/occweb-deploy.tar -C /var/www/html/custom_apps/occweb && rm /tmp/occweb-deploy.tar'"
|
||||
|
||||
# 3. Eigendom herstellen — tar bewaart de lokale uid (bv. 1000), niet www-data
|
||||
ssh nc01 "docker exec nextcloud-aio-nextcloud chown -R www-data:www-data /var/www/html/custom_apps/occweb"
|
||||
# 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/occweb"
|
||||
|
||||
# 4. Alleen bij een fresh install nodig (overslaan bij een update van een al-enabled app):
|
||||
ssh nc01 "docker exec -u www-data nextcloud-aio-nextcloud php occ app:enable 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 occweb"
|
||||
```
|
||||
|
||||
> **Gotcha — nooit `ssh host "docker exec container bash -c 'cat > file'"` met lokale stdin
|
||||
> gebruiken**: dat maakt een leeg bestand. Altijd `scp` → `docker cp`, zoals hierboven.
|
||||
> **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.
|
||||
|
||||
## ⚠️ Cruciaal bij een `<version>`-bump in `appinfo/info.xml`
|
||||
## ⚠️ Critical after bumping `<version>` in `appinfo/info.xml`
|
||||
|
||||
Dit is **niet optioneel** en blokkeert bij overslaan niet alleen occ-commando's maar ook
|
||||
**gewoon inloggen op de webinterface** (zelf ondervonden op 2026-09-25: na een deploy met
|
||||
een nieuwe `<version>` maar zonder onderstaande stap toonde Nextcloud voor iedereen een
|
||||
upgrade-scherm i.p.v. de loginpagina).
|
||||
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 houdt `installed_version` per app bij in de database (`oc_appconfig`), los van
|
||||
`<version>` in `info.xml`. Na het handmatig vervangen van bestanden (i.p.v. via de appstore
|
||||
of `occ upgrade`) lopen die twee uit elkaar → Nextcloud zet de hele instantie op
|
||||
"needs upgrade", wat ook de login blokkeert totdat je dit synct:
|
||||
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 nc01 "docker exec -u www-data nextcloud-aio-nextcloud php occ config:app:set occweb installed_version --value='X.Y.Z'"
|
||||
ssh <docker-host> "docker exec -u www-data nextcloud-aio-nextcloud php occ config:app:set occweb installed_version --value='X.Y.Z'"
|
||||
```
|
||||
|
||||
(zelfde `X.Y.Z` als de nieuwe `<version>`). Verifieer met `occ status` dat
|
||||
`needsDbUpgrade: false` weer klopt.
|
||||
(use the same `X.Y.Z` as the new `<version>`). Verify with `occ status` that
|
||||
`needsDbUpgrade: false` again.
|
||||
|
||||
## PHP-FPM herstarten na elke deploy
|
||||
## Restart PHP-FPM after every deploy
|
||||
|
||||
`occ app:disable`/`app:enable` leegt PHP's opcache niet — een update kan zonder restart
|
||||
onopgemerkt niet actief worden (routes die stil 404'en is het typische symptoom). Graceful
|
||||
reload i.p.v. hard restart (behoudt actieve requests):
|
||||
`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 nc01 "docker exec nextcloud-aio-nextcloud ps aux | grep 'php-fpm: master'" # zoek de PID
|
||||
ssh nc01 "docker exec nextcloud-aio-nextcloud kill -USR2 <master-pid>"
|
||||
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` werkt hier niet direct (de supervisord-socket zit niet op het standaardpad
|
||||
binnen deze AIO-container) — vandaar de handmatige PID-lookup.
|
||||
`supervisorctl` won't work directly inside this container (its socket isn't at the
|
||||
default path) — hence the manual PID lookup.
|
||||
|
||||
## Verwijderen
|
||||
## Removing the app
|
||||
|
||||
```bash
|
||||
ssh nc01 "docker exec -u www-data nextcloud-aio-nextcloud php occ app:disable occweb && \
|
||||
ssh <docker-host> "docker exec -u www-data nextcloud-aio-nextcloud php occ app:disable occweb && \
|
||||
docker exec nextcloud-aio-nextcloud rm -rf /var/www/html/custom_apps/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 de OCCWeb-terminal voor directe SQL-queries tegen de NC-database.
|
||||
Statements scheiden met `;`, Shift+Enter voor nieuwe regel, Enter om te sturen.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user