Addons

Ein Addon bringt einen Dienst in deine Projekte, den Envoryx nicht selbst mitliefert: phpMyAdmin neben der Datenbank, ein Elasticsearch für eine App, die darauf besteht, ein Keycloak, um Single Sign-on auszuprobieren. Eine kurze YAML-Datei beschreibt einen Container pro Projekt, und sobald ein Admin die Datei installiert hat, kann jedes Projekt den Dienst in seinem Bereich Dienste hinzufügen. Eine neue Envoryx-Version brauchst du dafür nicht.

Redis, Mailpit, die Suchmaschinen, Ollama und der Objektspeicher bleiben eingebaut, weil sie Extras haben, die ein Addon nicht bieten kann (das Mailpit-Postfach, Modell-Downloads, Bucket-Policies). Addons stehen daneben.

Ein Addon installieren

Addon-Dateien liegen in /config/addons/<name>.yml, und du verwaltest sie unter Einstellungen → Addons, wofür du Admin sein musst. Es gibt drei Wege hinein:

• Beispiele listet fünf Dateien, die mit Envoryx kommen. Installier eine so, wie sie ist, oder pass sie vorher an.
• Neues Addon öffnet einen Editor mit einer Startdatei, und Bearbeiten ändert eine, die du schon installiert hast.
• Von einer URL installieren holt eine Datei über http(s), zum Beispiel einen Raw-Link von GitHub.

Die Beispiele decken ab, wonach am häufigsten gefragt wird. phpMyAdmin öffnet sich schon angemeldet an der MySQL- oder MariaDB-Datenbank des Projekts. pgAdmin ist das Gegenstück für PostgreSQL, im Desktop-Modus und ohne Login; seine Karte zeigt Host, Benutzer und Passwort der Datenbank, damit du sie als Server eintragen kannst. Elasticsearch 9 oder 8 läuft als ein Knoten ohne Security und kann seinen Port für Desktop-Clients veröffentlichen. Soketi ist ein Pusher-kompatibler WebSocket-Server für Laravel Echo und Broadcasting, Browser erreichen ihn über seine Weboberflächen-Adresse. Keycloak 26 läuft im Entwicklungsmodus mit einem Admin-Passwort, das pro Projekt erzeugt wird.

Envoryx prüft jede Datei beim Speichern: Einen unbekannten Schlüssel, einen Namen, den Envoryx selbst benutzt, ein Image, das keine gültige Referenz ist, oder einen Platzhalter, den das Addon nicht füllen kann, lehnt es mit Begründung ab. Eine Datei in /config/addons, die sich nicht lesen lässt, steht mit ihrem Fehler in der Liste, ein Tippfehler per SSH verschwindet also nicht still. Eine Datei darf bis zu 64 KB groß sein.

Im Projekt hinzufügen

Installierte Addons erscheinen unten im Bereich Dienste des Projekts als phpMyAdmin hinzufügen und so weiter, mit einer Version zur Auswahl und, wenn das Addon es anbietet, Port auf dem Host veröffentlichen. Entwickler können Addons in ihren Projekten hinzufügen, ändern und entfernen; nur das Installieren der Dateien ist Admin-Sache.

Beim Hinzufügen entsteht der Container im Projektnetzwerk. Gibt das Addon deiner Anwendung Variablen mit, werden die Anwendungscontainer damit neu erstellt. Die Karte zeigt danach die Adresse der Weboberfläche, Host und Port im Projekt, den Host-Port, die Volumes, das Image, die Zugangsdaten, die du kennen solltest, und unter Injiziert die Variablen, die deine Anwendung bekommt.

Ein Addon überschreibt nie eine Variable, die schon vergeben ist. Die von Envoryx (DB_HOST, ENVORYX_URL und der Rest) und die eigenen Variablen des Projekts gewinnen immer, und wenn zwei Addons denselben Namen injizieren, behält ihn das erste. Was nicht durchgekommen ist, listet die Karte unter Nicht injiziert. So siehst du auf einen Blick, dass das DB_HOST eines Addons nicht das ist, was deine Anwendung benutzt.

Ein Addon mit Weboberfläche bekommt über den Proxy eine eigene Adresse, https://<projekt>-<addon>.<basisdomain> (für shop und phpMyAdmin also https://shop-phpmyadmin.test), und dazu einen Host-Port, wie Mailpit.

Entfernst du ein Addon aus einem Projekt, wird sein Container gelöscht. Hält es Daten in Volumes, bestätigst du, indem du den Namen des Addons eintippst, und die Volumes gehen mit.

Ein eigenes schreiben

Am besten fängst du bei den Beispielen an, das sind echte Dateien, die funktionieren. So sieht phpMyAdmin aus:

/config/addons/phpmyadmin.yml

name: phpmyadmin
title: phpMyAdmin
description: Web UI for MySQL and MariaDB, signed in to the project database.
homepage: https://www.phpmyadmin.net
versions:
  - version: "5.2"
    image: phpmyadmin:5.2
    default: true
port: 80
webUI: true
env:
  PMA_HOST: "{{database.host}}"
  PMA_PORT: "{{database.port}}"
  PMA_USER: "{{database.user}}"
  PMA_PASSWORD: "{{database.password}}"
  UPLOAD_LIMIT: 512M

Das sind alle Schlüssel, die eine Datei haben kann:

Schlüssel	Was er tut
name	2-30 Kleinbuchstaben, Ziffern und Bindestriche; der Container heißt envoryx-<projekt>-addon-<name>. Ein Name, den Envoryx selbst benutzt, geht nicht.
title, description, homepage	Was die Oberfläche anzeigt. title ist ohne Angabe der Name.
versions	Mindestens eine, jeweils mit version und image. default: true markiert die, die ein Projekt ohne eigene Wahl bekommt, sonst ist es die erste.
hostname	Der Name im Projektnetzwerk, ohne Angabe der Name des Addons.
port	Worauf der Container lauscht: {{port}}, die Weboberfläche und der Host-Port nehmen ihn.
webUI	true gibt dem Addon eine eigene Adresse über den Proxy.
publishPort	true bietet Port auf dem Host veröffentlichen an, für Desktop-Clients.
command	Ersetzt das Kommando des Images, als Liste.
user	Der Benutzer im Container, etwa "1000:1000".
env	Die eigene Umgebung des Containers. Namen dürfen Kleinbuchstaben und Punkte enthalten, für Images, die ihre Einstellungen so lesen (discovery.type: single-node).
secrets	Namen von Secrets: 24 Zufallszeichen pro Projekt, benutzt als {{secret.<name>}}.
volumes	Benannte Volumes mit name und path; noBackup: true hält eins aus Backups heraus.
healthcheck	test wie bei Docker, dazu interval, timeout, startPeriod (jeweils bis 1h) und retries.
inject	Variablen für deine Anwendungscontainer. Nur normale Variablennamen ([A-Z_][A-Z0-9_]*).
credentials	Was die Karte anzeigt, jeweils mit label und value; secret: true maskiert den Wert, bis du ihn aufdeckst.

In den Werten gehen Platzhalter: {{host}} und {{port}} (das Addon im Projektnetzwerk), {{url}} (die Adresse der Weboberfläche, leer ohne webUI), {{project.slug}}, {{project.name}}, {{project.url}}, die primäre Datenbank des Projekts als {{database.type}}, {{database.host}}, {{database.port}}, {{database.name}}, {{database.user}} und {{database.password}} (leer, wenn das Projekt keine hat), und {{secret.<name>}} für jedes Secret, das du deklariert hast. Ein Addon, das ein eigenes Passwort will und deiner Anwendung sagt, wo es zu finden ist, sieht dann so aus:

secrets: [password]
env:
  WIDGET_PASSWORD: "{{secret.password}}"
inject:
  WIDGET_URL: "http://{{host}}:{{port}}"
credentials:
  - {label: Password, value: "{{secret.password}}", secret: true}

Betrachter bekommen den Wert geheimer Zugangsdaten gar nicht.

Was eine Datei nicht kann, ist genauso gewollt. Es gibt kein Feld für den privilegierten Modus, Capabilities, Host-Verzeichnisse, das Host-Netzwerk oder Geräte, und unbekannte Schlüssel sind Fehler. Ein Addon läuft immer mit benannten Volumes im Netzwerk seines Projekts, wie die eingebauten Dienste. Auch eins, das du von einer URL installierst, kann einem Container also nicht deinen Host ausliefern.

Eine Datei ändern oder entfernen

Jedes Projekt behält eine Kopie der Definition, die es betreibt, zusammen mit seinen erzeugten Secrets. Speicherst du eine neue Version einer installierten Datei, wird diese Kopie in jedem Projekt aktualisiert, das das Addon nutzt. Neue Secrets werden erzeugt, vorhandene bleiben, und eine Version, die die Datei nicht mehr nennt, fällt auf den Standard zurück. Die Container ziehen beim nächsten Start oder Neustart des Projekts nach: der des Addons und, wenn sich die injizierten Variablen geändert haben, auch die Anwendungscontainer.

Eine Datei, die ein Projekt noch nutzt, lässt sich nicht löschen; Envoryx sagt dir, welche Projekte das sind. Verschwindet die Datei trotzdem, weil jemand sie von Hand aus /config/addons entfernt hat, betreibt das Projekt seine Kopie weiter, kann sie aber nicht mehr ändern.

Backups, Kopien und envoryx.yml

Ein Datenbank-Backup, ob von Hand, nach Zeitplan oder vor einem Upgrade, archiviert auch jedes Addon-Volume ohne noBackup, als addon-<name>-<volume>.tar.gz. Solange die Volumes gelesen werden, ist der Container des Addons gestoppt, damit das Archiv stimmig ist; danach startet er wieder. Stellst du den Datenbankteil eines Backups wieder her, werden diese Volumes geleert und die Archive ausgepackt, für die Addons, die das Projekt noch hat. Ein Snapshot einer einzelnen Datenbank lässt die Addon-Volumes weg.

Ein Duplikat bekommt dieselben Addons mit eigenen Secrets, neuen Host-Ports und leeren Volumes. Beim Umbenennen ziehen die Volumes mit.

In der envoryx.yml stehen die Addons des Projekts unter addons:. Auf dem Server, auf den du die Datei anwendest, muss die Addon-Datei installiert sein:

addons:
  phpmyadmin: true                           # die Standardversion
  elasticsearch: {version: "8", exposePort: true}

envoryx up --prune entfernt ein Addon, das die Datei nicht mehr nennt, zusammen mit seinen Volumes.

Auf einer verwalteten Instanz kann der Tarif des Hosters Addons auslassen, dann gibt es sie auf dieser Instanz nicht.