Apps verwalten #

Ein Teil des Funktionsumfangs von owncloud.online steckt in Apps: Papierkorb, Versionen, externe Speicher und Freigaben sind ebenso Apps wie später nachinstallierte Erweiterungen. Eine App kommt auf drei Wegen in eine Instanz: über den Markt in der Weboberfläche, als Paket von Hand und über occ. Diese Seite beschreibt außerdem, wie Sie Apps ein- und ausschalten, wie Sie Version und Verträglichkeit prüfen und was beim Entfernen einer App mit ihren Daten geschieht.

Es gibt zwei Sorten von Apps:

• Mitgelieferte Apps stehen in core/shipped.json. Sie lassen sich abschalten, aber nicht entfernen. Drei davon, files, dav und federatedfilesharing, lassen sich nicht einmal abschalten; occ app:disable bricht bei ihnen mit „can't be disabled.“ ab.
• Nachinstallierte Apps kommen aus dem Marketplace oder als Paket und liegen normalerweise in apps-external/. Nur sie lassen sich wieder löschen.

Die Liste in core/shipped.json und das Release-Archiv decken sich nicht ganz: encryption und configreport stehen in der Liste, liegen aber nicht im Archiv, sondern kommen aus dem Marketplace. Sie gelten trotzdem als mitgeliefert und lassen sich nur abschalten. Umgekehrt liegen comments, systemtags und oco_mcp im Archiv unter apps/, stehen aber nicht in der Liste.

Vorhandene Apps anzeigen #

sudo -u www-data php8.4 occ app:list

Die Ausgabe ist nach enabled und disabled getrennt und nennt zu jeder App ihr Verzeichnis; die Version steht bei den aktiven Apps dabei, bei den abgeschalteten erst mit --disabled. Nützliche Einschränkungen:

# nur aktive Apps
sudo -u www-data php8.4 occ app:list --enabled

# kurze Liste, nur Name und Version
sudo -u www-data php8.4 occ app:list --minimal

# nur Apps, die nicht in core/shipped.json stehen (Gegenstück: --shipped true)
sudo -u www-data php8.4 occ app:list --shipped false

# Verzeichnis einer einzelnen App
sudo -u www-data php8.4 occ app:getpath files_external

In der Weboberfläche zeigt Einstellungen → Administration → Apps dieselbe Liste unter der Überschrift Verwaltung der Apps.

Weg 1: über den Markt in der Weboberfläche #

Der Markt ist selbst eine App (market). Ist sie aktiv, erscheint für Administratoren im App-Menü links oben der Eintrag Markt.

Die linke Spalte führt durch den Katalog:

Eine App wird über ihre Detailseite installiert (Details, dann Installieren). Danach liegt sie im beschreibbaren App-Verzeichnis (siehe Schreibrechte) und ist aktiviert.

Der Katalog, den der Markt abfragt, steht in appstoreurl. Ohne Eintrag ist das https://marketplace.owncloud.online. Zwei weitere Werte sind möglich:

# fest eingebauter Katalog der Markt-App, ohne Netzzugriff
sudo -u www-data php8.4 occ config:system:set appstoreurl --value local

# eigener Katalog im Dateisystem
sudo -u www-data php8.4 occ config:system:set \
    appstoreurl --value file:///srv/katalog

Ein file://-Pfad oder das Schlüsselwort local schalten den Markt auf einen örtlichen Katalog um; jeder andere Wert wird als Adresse eines Katalog-Servers behandelt.

Apps mit API-Schlüssel #

Einige Apps liefert der Marketplace nur an Instanzen aus, die einen API-Schlüssel mitsenden. Ohne Schlüssel fehlen sie im Katalog, und der Download wird mit HTTP 401 abgewiesen. Den Schlüssel erhalten Sie auf Anfrage von der BW-Tech GmbH.

Mit owncloud.online 11.0.25 betrifft das diese Apps:

Schlüssel in der Weboberfläche eintragen:

1. Im App-Menü Markt öffnen.
2. In der linken Spalte unter Einstellungen auf API Schlüssel hinzufügen klicken (förmlich: API Key hinzufügen).
3. Im Dialog Marketplace-API-Key den Schlüssel in das Feld Dein persönlicher API-Key einfügen und Speichern klicken.

Nach dem Speichern lädt der Markt den Katalog neu, und die zusätzlichen Apps erscheinen in der Liste. Bei einem falschen Schlüssel meldet der Dialog „Der API-Key ist ungültig!“. Ist ein Schlüssel hinterlegt, heißt der Eintrag Bearbeite API Schlüssel (förmlich: API Key bearbeiten). Erscheinen die Apps nicht, hilft Cache leeren.

Auf der Kommandozeile setzen Sie den Schlüssel als App-Wert oder in config/config.php:

sudo -u www-data php8.4 occ config:app:set market key --value '<SCHLÜSSEL>'

'marketplace.key' => '<SCHLÜSSEL>',

Der Eintrag in der config.php hat Vorrang. Steht er dort, lässt sich der Schlüssel in der Oberfläche nicht mehr ändern; der Markt meldet dann, dass er in der config.php gesetzt ist. Nach dem Setzen auf der Kommandozeile im Markt Cache leeren aufrufen, damit der Katalog neu geladen wird.

Danach installieren Sie die Apps wie jede andere über ihre Detailseite oder mit occ market:install <app_id>.

Weg 2: Paket von Hand ablegen #

Dieser Weg braucht weder Netzzugang noch die Markt-App und ist der einzige, der auch in einer Instanz mit schreibgeschütztem App-Verzeichnis funktioniert. Die Dateien legt dann nicht der Webserver ab, sondern Sie selbst.

Ein App-Paket ist ein .tar.gz, das ein einzelnes Verzeichnis mit der Datei appinfo/info.xml enthält. Der Verzeichnisname muss der <id> aus dieser Datei entsprechen, denn der Server sucht eine App ausschließlich unter einem Verzeichnis mit ihrem Bezeichner.

cd /var/www/owncloud.online/apps-external
sudo tar -xzf /pfad/zum/paket.tar.gz
sudo chown -R www-data:www-data /var/www/owncloud.online/apps-external/<app_id>
sudo -u www-data php8.4 /var/www/owncloud.online/occ app:enable <app_id>

Fehlt apps-external/ in Ihrer Instanz, richten Sie es wie im Abschnitt Apps außerhalb von apps/ ablegen ein. Pakete unter apps/ überschreibt das nächste Server-Update.

Das Aktivieren erledigt die Einrichtung mit: Datenbankmigrationen der App, appinfo/install.php, Registrierung ihrer Hintergrund-Jobs und die Reparaturschritte für die Installation laufen dabei. Vorher prüft der Server die Abhängigkeiten und bricht ab, wenn eine nicht erfüllt ist.

Wird eine bereits vorhandene App durch eine neuere Fassung ersetzt, genügt app:enable nicht. Die Migrationen der neuen Version laufen erst mit:

sudo -u www-data php8.4 occ upgrade

Verglichen wird dabei die Version aus appinfo/info.xml mit dem in der Datenbank vermerkten Wert installed_version. Bleiben Haupt- und Nebenversion gleich (etwa 1.3.10 und 1.3.11), trägt der Server nur die neue Nummer ein und führt keine Migrationen aus.

Apps außerhalb von apps/ ablegen #

Ein Server-Update ersetzt den Codebaum und damit alles, was unter apps/ liegt. Damit nachinstallierte Apps das überstehen, sieht die Konfiguration ein zweites Verzeichnis vor. Neuinstallationen tragen beide Verzeichnisse bei der Einrichtung selbst in config/config.php ein, apps-external/ als beschreibbar. In älteren Instanzen ergänzen Sie den Eintrag von Hand:

'apps_paths' => [
	[
		'path' => OC::$SERVERROOT.'/apps',
		'url' => '/apps',
		'writable' => false,
	],
	[
		'path' => OC::$SERVERROOT.'/apps-external',
		'url' => '/apps-external',
		'writable' => true,
	],
],

Jeder Eintrag braucht alle drei Schlüssel: path als absoluter Pfad im Dateisystem, url als Pfad relativ zum Web-Wurzelverzeichnis mit führendem Schrägstrich, und writable. Neue Apps landen ausschließlich in dem Verzeichnis, dessen writable auf true steht; gibt es mehrere, gewinnt das erste. Ist apps_paths gar nicht gesetzt, benutzt der Server apps/ und behandelt es als beschreibbar.

Das Verzeichnis muss existieren, bevor Sie es eintragen; andernfalls startet der Server nicht mehr, sondern meldet „App directory … not found!“.

Weg 3: über occ #

Die vier market:-Befehle bringt die Markt-App mit. Sie stehen nur zur Verfügung, solange diese App aktiviert ist.

# Bezeichner aller Apps im Katalog
sudo -u www-data php8.4 occ market:list

# App aus dem Katalog installieren und aktivieren
sudo -u www-data php8.4 occ market:install <app_id>

# mehrere auf einmal
sudo -u www-data php8.4 occ market:install <app_id> <app_id>

# ein Paket installieren, das bereits im Dateisystem liegt
sudo -u www-data php8.4 occ market:install --local /pfad/zum/paket.tar.gz

market:install auf eine bereits vorhandene App spielt ein verfügbares Update innerhalb derselben Hauptversion ein. Liegt im Katalog nur eine neue Hauptversion, passiert nichts; stattdessen erscheint der Hinweis „Major update is available, use market:upgrade --major <app_id>.“

Updates:

# nur anzeigen, welche Updates es gibt
sudo -u www-data php8.4 occ market:upgrade --list

# eine bestimmte App aktualisieren
sudo -u www-data php8.4 occ market:upgrade <app_id>

# alle Apps mit verfügbarem Update
sudo -u www-data php8.4 occ market:upgrade --all

# Hauptversionswechsel ausdrücklich zulassen
sudo -u www-data php8.4 occ market:upgrade --major <app_id>

# aus einem örtlich vorliegenden Paket aktualisieren
sudo -u www-data php8.4 occ market:upgrade --local /pfad/zum/paket.tar.gz

Ohne --major lehnt der Befehl einen Wechsel der Hauptversion ab. Das ist Absicht: Ein solcher Wechsel kann Einstellungen und Datenbankschema der App verändern und gehört auf einen Zeitpunkt, an dem eine Sicherung vorliegt.

market:install, market:upgrade und market:uninstall prüfen zuerst, ob das App-Verzeichnis beschreibbar ist. market:install und market:upgrade brechen sonst mit „Installing apps is not supported because the app folder is not writable.“ ab, market:uninstall mit „Un-Installing apps is not supported because the app folder is not writable.“.

Die Apps unter apps/ kommen mit dem Server. Sie stecken im Release-Archiv owncloud-online-<version>.tar.gz beziehungsweise .zip unter github.com/BWTECH-github/owncloud.online/releases und werden nicht einzeln nachinstalliert, sondern mit dem Server aktualisiert. Zu jedem Release gehören außerdem SHA256SUMS.txt zur Prüfung der Archive, sbom-owncloud-online-<version>.cdx.json, release-manifest.json und removed-release-files.txt. Diese Seite beschreibt den Stand 11.0.25.

Aktivieren und abschalten #

sudo -u www-data php8.4 occ app:enable <app_id>
sudo -u www-data php8.4 occ app:disable <app_id>

Eine App lässt sich auch auf bestimmte Gruppen beschränken. Sie ist dann nur für Mitglieder dieser Gruppen vorhanden:

sudo -u www-data php8.4 occ app:enable <app_id> --groups buchhaltung -g vertrieb

In der Weboberfläche stehen unter Einstellungen → Administration → Apps an jeder App die Schaltflächen Aktivieren beziehungsweise Deaktivieren und die Auswahl Nur für bestimmte Gruppen aktivieren.

Zwei Punkte, die regelmäßig überraschen:

• Eine App bringt ihre occ-Befehle nur mit, solange sie aktiviert ist. Nach app:disable files_external verschwinden alle files_external:*-Befehle aus occ list, nach app:disable market alle market:*-Befehle.
• Die Reparaturschritte einer App für die Deinstallation laufen nur beim Abschalten über die Weboberfläche. occ app:disable setzt den Zustand direkt und überspringt sie. Die Daten der App bleiben in beiden Fällen erhalten, siehe unten.

Apps mit dem Typ filesystem, prelogin, authentication, logging, prevent_group_restriction oder theme lassen sich nicht auf Gruppen beschränken; app:enable --groups bricht bei ihnen mit „can't be enabled for groups.“ ab. Von den Theme-Apps kann immer nur eine aktiv sein: Das Aktivieren einer zweiten scheitert mit „… can't be enabled until … is disabled.“

Version und Verträglichkeit prüfen #

Jede App erklärt in appinfo/info.xml, mit welchen Server- und PHP-Versionen sie zusammenarbeitet. Beim Aktivieren über occ app:enable und über Einstellungen → Administration → Apps wird das geprüft. occ market:install prüft vor dem Einschalten nur, ob die App zur Serverversion passt; fehlende PHP-Erweiterungen oder Programme fallen dann erst im Betrieb auf. Schlägt die Prüfung fehl, nennt die Meldung die unerfüllte Bedingung:

Im Markt steht das Ergebnis unter Installierte Apps in der Spalte Kompatibilität: entweder OK oder Fehlende Abhängigkeiten samt Aufzählung des Fehlenden. Unter Einstellungen → Administration → Apps ist die Schaltfläche Aktivieren in diesem Fall ausgegraut, darüber steht „Die App kann nicht installiert werden, weil die folgenden Abhängigkeiten nicht erfüllt sind:“.

Zwei weitere Hinweise erscheinen dort, ohne die Installation zu verhindern: Fehlt in der info.xml die minimale oder die maximale Serverversion, meldet die Oberfläche das ausdrücklich. Solche Apps wurden nicht gegen diese Serverversion geprüft.

Zwei Werkzeuge auf der Kommandozeile:

# Code einer App gegen die Regeln der Server-API prüfen,
# dazu Pflichtfelder in info.xml
sudo -u www-data php8.4 occ app:check-code <app_id>

# Signatur einer App prüfen, sofern sie signiert ist
sudo -u www-data php8.4 occ integrity:check-app <app_id>

Bringt ein Paket eine appinfo/signature.json mit, prüft der Server die Signatur bereits bei der Installation und lehnt das Paket bei Abweichungen ab. Unsignierte Pakete werden ohne diese Prüfung installiert.

Schreibrechte auf das App-Verzeichnis #

Steht im Markt oben der Kasten „Installieren und Updaten von Apps nicht unterstützt!“ mit dem Zusatz „Dies ist ein geclustertes Setup oder der Web-Server hat keine Berechtigung in das apps Verzeichnis zu schreiben.“, dann trifft eine von zwei Bedingungen nicht zu:

1. operation.mode steht auf single-instance. Beim Wert clustered-instance unterbleibt die Installation aus dem Katalog grundsätzlich, weil sie ohnehin auf jedem Knoten einzeln erfolgen müsste.
2. Das Verzeichnis, dessen writable in apps_paths auf true steht, ist für den Webserver-Benutzer les- und schreibbar. Ist kein Verzeichnis als beschreibbar markiert, vermerkt das Protokoll „No application directories are marked as writable.“

Der Hinweis bedeutet nicht, dass die Instanz keine Apps bekommen kann. Er bedeutet nur, dass der Webserver sie nicht selbst ablegen darf. Weg 2 bleibt offen: Dort schreibt Ihr eigenes Konto die Dateien, nicht der Webserver.

Beide Bedingungen prüfen:

sudo -u www-data php8.4 occ config:system:get operation.mode
sudo -u www-data test -w /var/www/owncloud.online/apps-external && echo beschreibbar

Eine App wieder loswerden #

Es gibt zwei Stufen, und sie tun Verschiedenes.

Abschalten lässt Code und Daten liegen und macht die App nur unsichtbar:

sudo -u www-data php8.4 occ app:disable <app_id>

Entfernen löscht zusätzlich das Verzeichnis der App:

sudo -u www-data php8.4 occ market:uninstall <app_id>

In der Weboberfläche entspricht dem die Schaltfläche App deinstallieren unter Einstellungen → Administration → Apps. Sie erscheint nur an Apps, die nicht mitgeliefert sind und gerade nicht aktiv sind.

Was dabei mit den Daten geschieht:

Das Entfernen räumt also nur den Code weg. Der Server löscht ausdrücklich keine Tabellen, keine Einstellungen und keine Benutzervorgaben. Wird dieselbe App später wieder installiert, findet sie ihren alten Zustand vor. Das ist meist erwünscht; wer wirklich aufräumen will, muss die Reste von Hand entfernen:

# vorhandene Einstellungen der App ansehen
sudo -u www-data php8.4 occ config:list <app_id>

# einzelnen Wert löschen
sudo -u www-data php8.4 occ config:app:delete <app_id> <schlüssel>

Datenbanktabellen einer entfernten App bleiben bestehen. Wer sie loswerden will, löscht sie nach einer Sicherung direkt in der Datenbank, siehe Datenbank.

Drei Fälle, in denen das Entfernen abgelehnt wird:

• Mitgelieferte Apps, auch encryption und configreport: „Shipped apps cannot be uninstalled“. Für sie gibt es nur app:disable.
• Die Markt-App selbst: „Market app can not uninstall itself.“
• Apps, deren Verzeichnis ein .git enthält: „App … is a git clone - it will not be deleted.“ Ein solches Verzeichnis wird nie automatisch gelöscht.

Fehlersuche #

Bleibt die Ursache unklar, hilft das Serverprotokoll weiter, siehe Serverprotokoll und Fehlermeldungen. Eine Übersicht aller occ-Befehle steht unter occ – die Kommandozeile.