LaunchPad/apps/backend/plugins/README.md

LaunchPad-Plugins

Jeder Unterordner hier ist ein Plugin. Erkannt wird alles, was eine index.js mit einem passenden Default-Export enthält – kein Rebuild des Docker-Images nötig, dieser Ordner wird zur Laufzeit als Volume eingebunden (siehe docker-compose.yml). Nach dem Hinzufügen/Ändern eines Plugins reicht ein Neustart des Backend-Containers:

docker compose restart backend

Minimalstruktur

apps/backend/plugins/mein-plugin/
└── index.js

export default {
  name: "mein-plugin",
  version: "1.0.0",
  description: "Kurze Beschreibung, erscheint unter Admin -> Plugins",

  // optional: Scanner erweitern
  setup(ctx) {
    ctx.registerSoftwareSignature({
      name: "Meine Software",
      category: "Sonstiges",
      icon: "🔧", // Emoji oder Icon-URL
      matches: (input) => !!input.body && /meine-software/i.test(input.body),
    });
  },

  // optional: eigene Geräte-Importquelle
  async importDevices() {
    return [
      { hostname: "beispiel", ip: "192.168.1.99", source: "plugin" },
    ];
  },
};

Beide Funktionen (setup, importDevices) sind optional – ein Plugin kann nur die eine, nur die andere, oder beide implementieren. Reines JavaScript (ESM), kein Build-Schritt nötig.

Was Plugins aktuell können

• Scanner registrieren: ctx.registerSoftwareSignature(...) in setup() fügt der automatischen Softwareerkennung (siehe apps/backend/src/scanner/softwareDetection.ts) eine zusätzliche Signatur hinzu, inklusive eigenem Icon. Wird bei jedem Geräte-Scan berücksichtigt.
• Geräte importieren: importDevices() liefert eine Liste von Geräten, die per Knopfdruck unter Admin -> Plugins importiert werden (POST /api/plugins/:name/import). Abgeglichen wird wie bei Scans über MAC/IP – ein erneuter Import überschreibt keine Gerätefelder, die der Nutzer zwischenzeitlich geändert hat, außer den scan-eigenen (siehe upsertDeviceFromScan).
• Icons bereitstellen: über icon an einer registrierten Signatur. Wird als Startwert für neu angelegte Dienste übernommen (wie category – niemals nachträglich überschrieben, siehe README Hauptprojekt).

Was (noch) nicht geht

• Eigene Admin-Menüpunkte/Unterseiten (aktuell erscheinen alle Plugins gesammelt auf einer Seite unter Admin -> Plugins, keine eigene Route pro Plugin).
• Kein Sandboxing: Plugin-Code läuft mit vollem Zugriff im Backend-Prozess. Nur Plugins aus vertrauenswürdiger Quelle einbinden.

Beispiel-Plugins

• example-signatures/ – registriert zwei zusätzliche Software-Signaturen (Homebridge, Uptime Kuma).
• static-import/ – importiert Geräte aus einer lokalen devices.json (standardmäßig leer, siehe devices.example.json für das Format).