Commit f48813
2026-03-02 13:55:54 Manuel Weiser: docs: Add SpoolmanDB Import and Spoolman API plugin documentation; update login and admin sections for SSO support| .gitignore .. | |
| @@ 65,4 65,6 @@ | |
| spec | |
| bump-version.sh | |
| _* | |
| - | local_cache |
| \ | No newline at end of file |
| + | local_cache |
| + | .opencode |
| + | AGENTS.md |
| \ | No newline at end of file |
| docs/de/00-inhalt.md .. | |
| @@ 26,6 26,8 @@ | |
| | 12 | [Farbverwaltung](12-farbverwaltung.md) | Farben für Filamente definieren | | |
| | 13 | [Tipps & Häufige Fragen](13-faq.md) | FAQ und Empfehlungen | | |
| | 14 | [Plugin: BambuLab](14-plugin-bambulab.md) | BambuLab-Druckertreiber-Plugin | | |
| + | | 15 | [Plugin: SpoolmanDB Import](15-plugin-spoolmandb.md) | Filamente aus der SpoolmanDB importieren | |
| + | | 16 | [Plugin: Spoolman API](16-plugin-spoolmanapi.md) | Spoolman-kompatible API für externe Tools | |
| --- | |
| docs/de/02-anmeldung.md .. | |
| @@ 14,6 14,14 @@ | |
| Nach erfolgreicher Anmeldung gelangen Sie direkt zum **Dashboard**. | |
| + | ### Single Sign-On (SSO) |
| + | |
| + | Wenn Ihr Administrator **OIDC (OpenID Connect)** konfiguriert hat, erscheint unterhalb des Login-Formulars ein zusätzlicher SSO-Button (z. B. „Login mit Authentik“). |
| + | |
| + | Klicken Sie auf den SSO-Button, um zu Ihrem Identity Provider weitergeleitet zu werden. Nach erfolgreicher Authentifizierung dort werden Sie automatisch in FilaMan eingeloggt. |
| + | |
| + | > 💡 **Hinweis:** SSO-Login funktioniert nur für Benutzer, die bereits ein Konto in FilaMan mit einer übereinstimmenden E-Mail-Adresse haben. Wenn Sie noch kein Konto haben, wenden Sie sich an Ihren Administrator. |
| + | |
| --- | |
| ← [Zurück: Einleitung](./01-einleitung.md) | [Weiter: Navigation & Benutzeroberfläche →](./03-navigation.md) | |
| docs/de/11-admin.md .. | |
| @@ 15,6 15,7 @@ | |
| | **Devices** | Geräte-Token-Verwaltung | | |
| | **System Extra Fields** | Systemweite Zusatzfelder für Spulen und Filamente | | |
| | **System** | Plugins und Systemverwaltung | | |
| + | | **OIDC / SSO** | OpenID Connect Single Sign-On Konfiguration | |
| --- | |
| @@ 196,7 197,38 @@ | |
| --- | |
| - | ## 11.6 Gefahrenzone |
| + | ## 11.6 OIDC / SSO |
| + | |
| + | **URL:** `http(s)://url/admin/oidc` |
| + | |
| + | > ⚠️ **Hinweis:** Die OIDC-Kachel im Admin-Panel ist nur klickbar, wenn FilaMan über **HTTPS** aufgerufen wird. Bei HTTP-Verbindungen zeigt die Kachel einen Hinweis, dass OIDC nur über HTTPS funktioniert, und ist nicht klickbar. |
| + | |
| + | In diesem Bereich können Administratoren **OpenID Connect (OIDC)** für Single Sign-On (SSO) konfigurieren. Benutzer können sich dann über einen externen Identity Provider anmelden (z. B. Authentik, Keycloak, Azure AD). |
| + | |
| + | ### Konfigurationsfelder |
| + | |
| + | | Einstellung | Beschreibung | |
| + | |-------------|-------------| |
| + | | **Aktiviert** | Toggle zum Aktivieren/Deaktivieren des OIDC-Logins | |
| + | | **Issuer URL** | Die Issuer-URL des OIDC-Providers (muss `https://` sein) | |
| + | | **Client ID** | Die beim OIDC-Provider registrierte Client-ID | |
| + | | **Client Secret** | Das Client-Secret (wird verschlüsselt in der Datenbank gespeichert) | |
| + | | **Scopes** | Angeforderte OIDC-Scopes (Standard: `openid email profile`) | |
| + | | **Button-Text** | Benutzerdefinierter Text für den SSO-Button auf der Login-Seite (z. B. „Login mit Authentik") | |
| + | |
| + | ### Voraussetzungen |
| + | |
| + | - **HTTPS erforderlich** — OIDC funktioniert nur, wenn FilaMan über HTTPS aufgerufen wird |
| + | - **Umgebungsvariable `OIDC_ENC_KEY`** — Muss gesetzt sein, um das Client-Secret zu verschlüsseln. Generieren mit: |
| + | ```bash |
| + | openssl rand -hex 32 |
| + | ``` |
| + | - **Nur bestehende Benutzer** — Nur Benutzer, die bereits in FilaMan existieren, können sich per OIDC anmelden. Die E-Mail-Adresse des Providers muss mit einem bestehenden Benutzerkonto übereinstimmen. Die E-Mail muss vom Provider als verifiziert markiert sein. |
| + | - **Keine automatische Erstellung** — OIDC-Login erstellt keine neuen Benutzerkonten |
| + | |
| + | --- |
| + | |
| + | ## 11.7 Gefahrenzone |
| Am unteren Ende des Admin-Panels befindet sich die rot markierte **Danger Zone** mit einer kritischen Aktion: | |
| docs/de/14-plugin-bambulab.md .. | |
| @@ 2,6 2,8 @@ | |
| Das **BambuLab-Plugin** ist ein Driver-Plugin, das FilaMan um die vollständige Integration von BambuLab 3D-Druckern erweitert. Es ermöglicht die Kommunikation über MQTT, die Verwaltung von AMS-Slots und das automatische Setzen von Filament-Einstellungen. | |
| + | > ⚠️ **Wichtig:** Die Steuerung des Druckers über FilaMan (z. B. Spulen im Drucker/AMS setzen) funktioniert nur, wenn der Drucker im **LAN-only Modus** UND im **Developer Mode** betrieben wird. |
| + | |
| **Installation:** → [Admin: Plugin-Verwaltung](./11-admin.md#115-system-plugin-verwaltung) | |
| --- | |
| @@ 152,4 154,4 @@ | |
| --- | |
| - | ← [Zurück: Tipps & FAQ](./13-faq.md) | [Weiter: Weitere Plugins →](#) |
| + | ← [Zurück: Tipps & FAQ](./13-faq.md) | [Weiter: Plugin: SpoolmanDB Import →](./15-plugin-spoolmandb.md) |
| /dev/null .. docs/de/15-plugin-spoolmandb.md | |
| @@ 0,0 1,134 @@ | |
| + | # Plugin: SpoolmanDB Import |
| + | |
| + | Das **SpoolmanDB Import-Plugin** ermöglicht den Import von Filament-Daten aus der [SpoolmanDB Community-Datenbank](https://github.com/Donkie/SpoolmanDB) direkt in FilaMan. Die SpoolmanDB ist eine offene, von der Community gepflegte Datenbank mit Filament-Informationen zahlreicher Hersteller. |
| + | |
| + | **Installation:** → [Admin: Plugin-Verwaltung](./11-admin.md#115-system-plugin-verwaltung) |
| + | |
| + | --- |
| + | |
| + | ## Übersicht |
| + | |
| + | | Eigenschaft | Wert | |
| + | |-------------|------| |
| + | | **Plugin-Typ** | Import | |
| + | | **Autor** | FilaMan | |
| + | | **Quelle** | [Fire-Devils/filaman-plugins](https://github.com/Fire-Devils/filaman-plugins) (Registry) | |
| + | | **Datenquelle** | [SpoolmanDB](https://github.com/Donkie/SpoolmanDB) (GitHub) | |
| + | | **Fähigkeiten** | Hersteller-Import, Filament-Import, Farben-Import, Durchmesser-Filter | |
| + | |
| + | --- |
| + | |
| + | ## Was ist die SpoolmanDB? |
| + | |
| + | Die [SpoolmanDB](https://github.com/Donkie/SpoolmanDB) ist eine von der 3D-Druck-Community gepflegte Open-Source-Datenbank, die Filament-Informationen vieler Hersteller enthält. Dazu gehören: |
| + | |
| + | - Hersteller-Namen |
| + | - Filament-Bezeichnungen und Materialtypen |
| + | - Farben (Einzel- und Multicolor) |
| + | - Durchmesser, Gewicht und Dichte |
| + | - Empfohlene Extruder- und Betttemperaturen |
| + | - Spulengewicht und Spulenmaterial |
| + | - Oberflächen-Eigenschaften (transluzent, leuchtend, etc.) |
| + | |
| + | --- |
| + | |
| + | ## Import-Seite |
| + | |
| + | Nach der Installation des Plugins finden Sie die Import-Seite unter: |
| + | |
| + | **Admin → System → SpoolmanDB Import** |
| + | |
| + | Die Import-Seite führt Sie in drei Schritten durch den Prozess. |
| + | |
| + | --- |
| + | |
| + | ## Schritt 1: Importmodus wählen |
| + | |
| + | ### Durchmesser-Filter |
| + | |
| + | Vor der Auswahl des Importmodus können Sie optional nach **Durchmesser** filtern: |
| + | |
| + | | Option | Beschreibung | |
| + | |--------|-------------| |
| + | | **Alle Durchmesser** | Keine Filterung | |
| + | | **1.75 mm** | Nur 1.75 mm Filamente (Standard) | |
| + | | **2.85 mm** | Nur 2.85 mm Filamente | |
| + | |
| + | ### Import-Modi |
| + | |
| + | | Modus | Beschreibung | |
| + | |-------|-------------| |
| + | | **Alles importieren** | Importiert alle Filamente und Hersteller aus der SpoolmanDB | |
| + | | **Nach Hersteller** | Importiert alle Filamente eines bestimmten Herstellers — wählen Sie den Hersteller aus dem Dropdown | |
| + | | **Einzelnes Filament** | Importiert ein bestimmtes Filament gezielt — wählen Sie Hersteller (optional als Filter) und Filament aus | |
| + | |
| + | --- |
| + | |
| + | ## Schritt 2: Vorschau |
| + | |
| + | Nach der Auswahl des Importmodus können Sie eine **Vorschau** laden. Je nach Modus wird angezeigt: |
| + | |
| + | - **Alles importieren:** Gesamtzahl der Hersteller und Filamente |
| + | - **Nach Hersteller:** Tabelle mit allen Filamenten des gewählten Herstellers (Name, Material, Durchmesser) |
| + | - **Einzelnes Filament:** Detailansicht mit allen verfügbaren Informationen (Hersteller, Name, Material, Durchmesser, Gewicht, Dichte, Farbe, Temperaturen) |
| + | |
| + | > **Tipp:** Prüfen Sie die Vorschau sorgfältig, bevor Sie den Import starten. |
| + | |
| + | --- |
| + | |
| + | ## Schritt 3: Import ausführen |
| + | |
| + | Klicken Sie auf **„Import starten"**, um die ausgewählten Daten in FilaMan zu importieren. |
| + | |
| + | ### Was wird importiert? |
| + | |
| + | | Daten | Beschreibung | |
| + | |-------|-------------| |
| + | | **Hersteller** | Werden als neue Hersteller in FilaMan angelegt (falls nicht bereits vorhanden) | |
| + | | **Filamente** | Werden als neue Filamente mit allen verfügbaren Informationen erstellt | |
| + | | **Farben** | Werden als neue Farben in der Farbverwaltung angelegt (falls nicht bereits vorhanden) | |
| + | |
| + | ### Duplikat-Erkennung |
| + | |
| + | - **Hersteller** werden anhand des Namens (case-insensitive) erkannt — bereits vorhandene werden übersprungen |
| + | - **Filamente** werden anhand der SpoolmanDB-ID erkannt — bereits importierte werden übersprungen |
| + | - **Farben** werden anhand des Hex-Codes erkannt — bereits vorhandene werden wiederverwendet |
| + | |
| + | > **Wichtig:** Bestehende Daten in FilaMan werden **nicht** überschrieben oder verändert. Der Import erstellt nur neue Einträge. |
| + | |
| + | ### Import-Ergebnis |
| + | |
| + | Nach Abschluss des Imports wird eine Zusammenfassung angezeigt: |
| + | |
| + | | Kategorie | Anzeige | |
| + | |-----------|---------| |
| + | | **Hersteller** | Anzahl erstellt / übersprungen | |
| + | | **Filamente** | Anzahl erstellt / übersprungen | |
| + | | **Farben** | Anzahl erstellt / übersprungen | |
| + | | **Fehler** | Liste eventueller Fehler (z. B. fehlende Hersteller-Zuordnung) | |
| + | |
| + | --- |
| + | |
| + | ## Importierte Daten |
| + | |
| + | Die folgenden Filament-Felder werden aus der SpoolmanDB übernommen (sofern vorhanden): |
| + | |
| + | | SpoolmanDB-Feld | FilaMan-Feld | |
| + | |-----------------|-------------| |
| + | | `manufacturer` | Hersteller | |
| + | | `name` + `material` | Bezeichnung | |
| + | | `material` | Materialtyp | |
| + | | `fill` | Materialuntergruppe (z. B. Glasfaser, Carbon) | |
| + | | `diameter` | Durchmesser | |
| + | | `weight` | Rohmaterialgewicht | |
| + | | `spool_weight` | Standard-Spulengewicht | |
| + | | `spool_type` | Spulenmaterial | |
| + | | `density` | Dichte | |
| + | | `color_hex` / `color_hexes` | Farben (Einzel-/Multicolor) | |
| + | | `multi_color_direction` | Multicolor-Stil (Gradient/Striped) | |
| + | | `translucent` / `glow` / `finish` | Oberflächentyp | |
| + | | `extruder_temp`, `bed_temp` etc. | Zusatzfelder (custom_fields) | |
| + | |
| + | --- |
| + | |
| + | ← [Zurück: Plugin: BambuLab](./14-plugin-bambulab.md) | [Weiter: Plugin: Spoolman API →](./16-plugin-spoolmanapi.md) |
| /dev/null .. docs/de/16-plugin-spoolmanapi.md | |
| @@ 0,0 1,164 @@ | |
| + | # Plugin: Spoolman API |
| + | |
| + | Das **Spoolman API-Plugin** stellt eine vollständig Spoolman-kompatible REST-API bereit, die auf das interne Datenmodell von FilaMan abgebildet wird. Externe Tools wie **Moonraker**, **OctoPrint** und andere können FilaMan damit als **Drop-in-Ersatz für Spoolman** nutzen. Im Gegensatz zu Spoolman selbst enthält dieses Plugin eine **IP-basierte Zugriffskontrolle** — eine Sicherheitsebene, die in Spoolman fehlt. |
| + | |
| + | **Installation:** → [Admin: Plugin-Verwaltung](./11-admin.md#115-system-plugin-verwaltung) |
| + | |
| + | --- |
| + | |
| + | ## Übersicht |
| + | |
| + | | Eigenschaft | Wert | |
| + | |-------------|------| |
| + | | **Plugin-Typ** | Integration | |
| + | | **Autor** | FilaMan | |
| + | | **Quelle** | [Fire-Devils/filaman-plugins](https://github.com/Fire-Devils/filaman-plugins) (Registry) | |
| + | | **API-Pfad** | `/spoolman/api/v1/` | |
| + | | **Fähigkeiten** | Spoolman API v1-Kompatibilität, CRUD-Operationen, CSV/JSON-Export, IP-Zugriffskontrolle | |
| + | |
| + | --- |
| + | |
| + | ## Was ist Spoolman? |
| + | |
| + | [Spoolman](https://github.com/Donkie/Spoolman) ist eine verbreitete Open-Source-Software zur Verwaltung von 3D-Drucker-Filamenten. Viele Tools im 3D-Druck-Ökosystem (z. B. Moonraker, OctoPrint) unterstützen die Spoolman-API, um Filament-Verbrauch zu tracken und Spulen zu verwalten. |
| + | |
| + | Mit diesem Plugin kann FilaMan anstelle von Spoolman eingesetzt werden, ohne dass externe Tools umkonfiguriert werden müssen — sie sprechen einfach die gleiche API. |
| + | |
| + | --- |
| + | |
| + | ## Konfiguration externer Tools |
| + | |
| + | ### Moonraker (Klipper) |
| + | |
| + | Tragen Sie in Ihrer `moonraker.conf` folgendes ein: |
| + | |
| + | ```ini |
| + | [spoolman] |
| + | server: http://<filaman-host>:8000/spoolman |
| + | ``` |
| + | |
| + | Ersetzen Sie `<filaman-host>` durch die IP-Adresse oder den Hostnamen Ihrer FilaMan-Installation. |
| + | |
| + | ### OctoPrint |
| + | |
| + | Verwenden Sie in den Spoolman-Plugin-Einstellungen von OctoPrint die URL: |
| + | |
| + | ``` |
| + | http://<filaman-host>:8000/spoolman |
| + | ``` |
| + | |
| + | ### Andere Tools |
| + | |
| + | Jedes Tool, das die Spoolman-API unterstützt, kann mit der gleichen URL konfiguriert werden: |
| + | |
| + | ``` |
| + | http://<filaman-host>:8000/spoolman/api/v1/ |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## IP-Zugriffskontrolle |
| + | |
| + | Das Plugin bietet eine **IP-basierte Zugriffskontrolle**, mit der Sie einschränken können, welche Geräte auf die Spoolman-API zugreifen dürfen. |
| + | |
| + | ### Einstellungen |
| + | |
| + | Die Einstellungen finden Sie auf der Plugin-Seite im Admin-Bereich unter **Spoolman API**. |
| + | |
| + | | Einstellung | Beschreibung | |
| + | |-------------|-------------| |
| + | | **IP-Filter aktiviert** | Schaltet die IP-Zugriffskontrolle ein/aus. Standardmäßig **deaktiviert** (alle IPs erlaubt). | |
| + | | **Erlaubte IPs** | Liste der erlaubten IP-Adressen oder Bereiche | |
| + | |
| + | ### Unterstützte IP-Formate |
| + | |
| + | | Format | Beispiel | Beschreibung | |
| + | |--------|---------|-------------| |
| + | | **Wildcard** | `*` | Alle IPs erlauben | |
| + | | **Einzelne IP** | `192.168.1.5` | Exakte IP-Adresse | |
| + | | **CIDR-Bereich** | `192.168.1.0/24` | Gesamtes Subnetz | |
| + | | **Großer Bereich** | `10.0.0.0/8` | Großer Netzwerkbereich | |
| + | |
| + | > **Hinweis:** Wenn der IP-Filter aktiviert ist und eine nicht erlaubte IP zugreift, wird der Zugriff mit HTTP 403 (Forbidden) abgelehnt. |
| + | |
| + | --- |
| + | |
| + | ## API-Endpunkte |
| + | |
| + | Alle Spoolman-Endpunkte sind unter dem Pfad `/spoolman/api/v1/` verfügbar: |
| + | |
| + | ### System |
| + | |
| + | | Methode | Pfad | Beschreibung | |
| + | |---------|------|-------------| |
| + | | GET | `/info` | API-Informationen | |
| + | | GET | `/health` | Health-Check | |
| + | |
| + | ### Hersteller (Vendors) |
| + | |
| + | | Methode | Pfad | Beschreibung | |
| + | |---------|------|-------------| |
| + | | GET | `/vendor` | Alle Hersteller auflisten | |
| + | | POST | `/vendor` | Neuen Hersteller erstellen | |
| + | | GET | `/vendor/{id}` | Hersteller abrufen | |
| + | | PATCH | `/vendor/{id}` | Hersteller aktualisieren | |
| + | | DELETE | `/vendor/{id}` | Hersteller löschen | |
| + | |
| + | ### Filamente |
| + | |
| + | | Methode | Pfad | Beschreibung | |
| + | |---------|------|-------------| |
| + | | GET | `/filament` | Alle Filamente auflisten | |
| + | | POST | `/filament` | Neues Filament erstellen | |
| + | | GET | `/filament/{id}` | Filament abrufen | |
| + | | PATCH | `/filament/{id}` | Filament aktualisieren | |
| + | | DELETE | `/filament/{id}` | Filament löschen | |
| + | |
| + | ### Spulen (Spools) |
| + | |
| + | | Methode | Pfad | Beschreibung | |
| + | |---------|------|-------------| |
| + | | GET | `/spool` | Alle Spulen auflisten | |
| + | | POST | `/spool` | Neue Spule erstellen | |
| + | | GET | `/spool/{id}` | Spule abrufen | |
| + | | PATCH | `/spool/{id}` | Spule aktualisieren | |
| + | | DELETE | `/spool/{id}` | Spule löschen | |
| + | | PUT | `/spool/{id}/use` | Filament von Spule verbrauchen | |
| + | | PUT | `/spool/{id}/measure` | Spulengewicht messen | |
| + | |
| + | ### Weitere Endpunkte |
| + | |
| + | | Methode | Pfad | Beschreibung | |
| + | |---------|------|-------------| |
| + | | GET | `/material` | Materialtypen auflisten | |
| + | | GET | `/location` | Lagerorte auflisten | |
| + | | PATCH | `/location/{name}` | Lagerort umbenennen | |
| + | | GET | `/setting/{key}` | Einstellung abrufen | |
| + | | POST | `/setting/{key}` | Einstellung setzen | |
| + | |
| + | ### Export |
| + | |
| + | | Methode | Pfad | Beschreibung | |
| + | |---------|------|-------------| |
| + | | GET | `/export/spools` | Spulen exportieren (CSV/JSON) | |
| + | | GET | `/export/filaments` | Filamente exportieren (CSV/JSON) | |
| + | | GET | `/export/vendors` | Hersteller exportieren (CSV/JSON) | |
| + | | POST | `/backup` | Backup erstellen | |
| + | |
| + | --- |
| + | |
| + | ## Daten-Mapping |
| + | |
| + | Die Spoolman-API-Begriffe werden intern auf das FilaMan-Datenmodell abgebildet: |
| + | |
| + | | Spoolman-Begriff | FilaMan-Entsprechung | |
| + | |-----------------|---------------------| |
| + | | Vendor | Hersteller (Manufacturer) | |
| + | | Filament | Filament | |
| + | | Spool | Spule (Spool) | |
| + | | Location | Lagerort (Location) | |
| + | | Extra Fields | Zusatzfelder (Custom Fields) | |
| + | |
| + | --- |
| + | |
| + | ← [Zurück: Plugin: SpoolmanDB Import](./15-plugin-spoolmandb.md) | [Weiter: Weitere Plugins →](#) |
| docs/en/00-contents.md .. | |
| @@ 26,6 26,8 @@ | |
| | 12 | [Color Management](12-colors.md) | Defining colors for filaments | | |
| | 13 | [Tips & FAQ](13-faq.md) | Frequently asked questions | | |
| | 14 | [Plugin: BambuLab](14-plugin-bambulab.md) | BambuLab printer driver plugin | | |
| + | | 15 | [Plugin: SpoolmanDB Import](15-plugin-spoolmandb.md) | Import filaments from the SpoolmanDB database | |
| + | | 16 | [Plugin: Spoolman API](16-plugin-spoolmanapi.md) | Spoolman-compatible API for external tools | |
| --- | |
| docs/en/02-login.md .. | |
| @@ 14,6 14,14 @@ | |
| After a successful login you will be taken directly to the **Dashboard**. | |
| + | ### Single Sign-On (SSO) |
| + | |
| + | If your administrator has configured **OIDC (OpenID Connect)**, an additional SSO button appears below the login form (e.g. "Login with Authentik"). |
| + | |
| + | Click the SSO button to be redirected to your organization's identity provider. After successful authentication there, you will be automatically logged into FilaMan. |
| + | |
| + | > 💡 **Note:** SSO login only works for users who already have an account in FilaMan with a matching email address. If you don't have an account yet, contact your administrator. |
| + | |
| --- | |
| ← [Back: Introduction](01-introduction.md) | [Next: Navigation & UI →](03-navigation.md) | |
| docs/en/11-admin.md .. | |
| @@ 15,6 15,7 @@ | |
| | **Devices** | Device token management | | |
| | **System Extra Fields** | System-wide extra fields for spools and filaments | | |
| | **System** | Plugins and system management | | |
| + | | **OIDC / SSO** | OpenID Connect Single Sign-On configuration | |
| --- | |
| @@ 196,7 197,38 @@ | |
| --- | |
| - | ## 11.6 Danger Zone |
| + | ## 11.6 OIDC / SSO |
| + | |
| + | **URL:** `http(s)://url/admin/oidc` |
| + | |
| + | > ⚠️ **Note:** The OIDC card on the Admin Panel is only clickable when accessing FilaMan via **HTTPS**. On HTTP connections, the card displays a notice that OIDC requires HTTPS and is not clickable. |
| + | |
| + | This section allows administrators to configure **OpenID Connect (OIDC)** for Single Sign-On (SSO). Users can then log in using an external identity provider (e.g. Authentik, Keycloak, Azure AD). |
| + | |
| + | ### Configuration Fields |
| + | |
| + | | Setting | Description | |
| + | |---------|-------------| |
| + | | **Enabled** | Toggle to enable or disable OIDC login | |
| + | | **Issuer URL** | The OIDC provider's issuer URL (must be `https://`) | |
| + | | **Client ID** | The client ID registered with your OIDC provider | |
| + | | **Client Secret** | The client secret (stored encrypted in the database) | |
| + | | **Scopes** | OIDC scopes to request (default: `openid email profile`) | |
| + | | **Button Text** | Custom label for the SSO button on the login page (e.g. "Login with Authentik") | |
| + | |
| + | ### Requirements |
| + | |
| + | - **HTTPS required** — OIDC only works when FilaMan is accessed via HTTPS |
| + | - **`OIDC_ENC_KEY` environment variable** — Must be set for encrypting the client secret. Generate with: |
| + | ```bash |
| + | openssl rand -hex 32 |
| + | ``` |
| + | - **Existing users only** — Only users who already exist in FilaMan can log in via OIDC. The provider's email address must match an existing user account. The email must be verified by the provider. |
| + | - **No auto-creation** — OIDC login does not create new user accounts |
| + | |
| + | --- |
| + | |
| + | ## 11.7 Danger Zone |
| At the bottom of the Admin Panel you will find the red-highlighted **Danger Zone** with one critical action: | |
| docs/en/14-plugin-bambulab.md .. | |
| @@ 2,6 2,8 @@ | |
| The **BambuLab Plugin** is a Driver plugin that extends FilaMan with full BambuLab 3D printer integration. It enables communication via MQTT, AMS slot management, and automatic filament setting assignment. | |
| + | > ⚠️ **Important:** Controlling the printer via FilaMan (e.g. setting spools in the printer/AMS) only works when the printer is in **LAN-only Mode** AND **Developer Mode**. |
| + | |
| **Installation:** → [Admin: Plugin Management](./11-admin.md#115-system-plugin-management) | |
| --- | |
| @@ 152,4 154,4 @@ | |
| --- | |
| - | ← [Back: Tips & FAQ](./13-faq.md) | [Next: More Plugins →](#) |
| + | ← [Back: Tips & FAQ](./13-faq.md) | [Next: Plugin: SpoolmanDB Import →](./15-plugin-spoolmandb.md) |
| /dev/null .. docs/en/15-plugin-spoolmandb.md | |
| @@ 0,0 1,134 @@ | |
| + | # Plugin: SpoolmanDB Import |
| + | |
| + | The **SpoolmanDB Import Plugin** allows you to import filament data from the [SpoolmanDB community database](https://github.com/Donkie/SpoolmanDB) directly into FilaMan. SpoolmanDB is an open, community-maintained database containing filament information from numerous manufacturers. |
| + | |
| + | **Installation:** → [Admin: Plugin Management](./11-admin.md#115-system-plugin-management) |
| + | |
| + | --- |
| + | |
| + | ## Overview |
| + | |
| + | | Property | Value | |
| + | |----------|-------| |
| + | | **Plugin Type** | Import | |
| + | | **Author** | FilaMan | |
| + | | **Source** | [Fire-Devils/filaman-plugins](https://github.com/Fire-Devils/filaman-plugins) (Registry) | |
| + | | **Data Source** | [SpoolmanDB](https://github.com/Donkie/SpoolmanDB) (GitHub) | |
| + | | **Capabilities** | Manufacturer import, Filament import, Color import, Diameter filter | |
| + | |
| + | --- |
| + | |
| + | ## What is SpoolmanDB? |
| + | |
| + | [SpoolmanDB](https://github.com/Donkie/SpoolmanDB) is a community-maintained open-source database containing filament information from many manufacturers. It includes: |
| + | |
| + | - Manufacturer names |
| + | - Filament names and material types |
| + | - Colors (single and multi-color) |
| + | - Diameter, weight, and density |
| + | - Recommended extruder and bed temperatures |
| + | - Spool weight and spool material |
| + | - Surface properties (translucent, glow, etc.) |
| + | |
| + | --- |
| + | |
| + | ## Import Page |
| + | |
| + | After installing the plugin, you can find the import page at: |
| + | |
| + | **Admin → System → SpoolmanDB Import** |
| + | |
| + | The import page guides you through the process in three steps. |
| + | |
| + | --- |
| + | |
| + | ## Step 1: Choose Import Mode |
| + | |
| + | ### Diameter Filter |
| + | |
| + | Before selecting the import mode, you can optionally filter by **diameter**: |
| + | |
| + | | Option | Description | |
| + | |--------|-------------| |
| + | | **All diameters** | No filtering | |
| + | | **1.75 mm** | Only 1.75 mm filaments (default) | |
| + | | **2.85 mm** | Only 2.85 mm filaments | |
| + | |
| + | ### Import Modes |
| + | |
| + | | Mode | Description | |
| + | |------|-------------| |
| + | | **Import all** | Imports all filaments and manufacturers from SpoolmanDB | |
| + | | **By manufacturer** | Imports all filaments from a specific manufacturer — select the manufacturer from the dropdown | |
| + | | **Single filament** | Imports a specific filament — select manufacturer (optional filter) and filament | |
| + | |
| + | --- |
| + | |
| + | ## Step 2: Preview |
| + | |
| + | After selecting the import mode, you can load a **preview**. Depending on the mode, it shows: |
| + | |
| + | - **Import all:** Total count of manufacturers and filaments |
| + | - **By manufacturer:** Table listing all filaments from the chosen manufacturer (name, material, diameter) |
| + | - **Single filament:** Detail view with all available information (manufacturer, name, material, diameter, weight, density, color, temperatures) |
| + | |
| + | > **Tip:** Review the preview carefully before starting the import. |
| + | |
| + | --- |
| + | |
| + | ## Step 3: Execute Import |
| + | |
| + | Click **"Start Import"** to import the selected data into FilaMan. |
| + | |
| + | ### What Gets Imported? |
| + | |
| + | | Data | Description | |
| + | |------|-------------| |
| + | | **Manufacturers** | Created as new manufacturers in FilaMan (if not already present) | |
| + | | **Filaments** | Created as new filaments with all available information | |
| + | | **Colors** | Created as new colors in color management (if not already present) | |
| + | |
| + | ### Duplicate Detection |
| + | |
| + | - **Manufacturers** are matched by name (case-insensitive) — existing ones are skipped |
| + | - **Filaments** are matched by SpoolmanDB ID — previously imported ones are skipped |
| + | - **Colors** are matched by hex code — existing ones are reused |
| + | |
| + | > **Important:** Existing data in FilaMan is **never** overwritten or modified. The import only creates new entries. |
| + | |
| + | ### Import Result |
| + | |
| + | After the import completes, a summary is displayed: |
| + | |
| + | | Category | Display | |
| + | |----------|---------| |
| + | | **Manufacturers** | Count created / skipped | |
| + | | **Filaments** | Count created / skipped | |
| + | | **Colors** | Count created / skipped | |
| + | | **Errors** | List of any errors (e.g. missing manufacturer assignment) | |
| + | |
| + | --- |
| + | |
| + | ## Imported Data |
| + | |
| + | The following filament fields are imported from SpoolmanDB (if available): |
| + | |
| + | | SpoolmanDB Field | FilaMan Field | |
| + | |-----------------|---------------| |
| + | | `manufacturer` | Manufacturer | |
| + | | `name` + `material` | Designation | |
| + | | `material` | Material type | |
| + | | `fill` | Material subgroup (e.g. glass fiber, carbon) | |
| + | | `diameter` | Diameter | |
| + | | `weight` | Raw material weight | |
| + | | `spool_weight` | Default spool weight | |
| + | | `spool_type` | Spool material | |
| + | | `density` | Density | |
| + | | `color_hex` / `color_hexes` | Colors (single/multi-color) | |
| + | | `multi_color_direction` | Multi-color style (gradient/striped) | |
| + | | `translucent` / `glow` / `finish` | Finish type | |
| + | | `extruder_temp`, `bed_temp` etc. | Extra fields (custom_fields) | |
| + | |
| + | --- |
| + | |
| + | ← [Back: Plugin: BambuLab](./14-plugin-bambulab.md) | [Next: Plugin: Spoolman API →](./16-plugin-spoolmanapi.md) |
| /dev/null .. docs/en/16-plugin-spoolmanapi.md | |
| @@ 0,0 1,164 @@ | |
| + | # Plugin: Spoolman API |
| + | |
| + | The **Spoolman API Plugin** exposes a fully Spoolman-compatible REST API that maps to FilaMan's internal data model. External tools like **Moonraker**, **OctoPrint**, and others can use FilaMan as a **drop-in replacement for Spoolman**. Unlike Spoolman itself, this plugin includes **IP-based access control** — a security layer missing in Spoolman. |
| + | |
| + | **Installation:** → [Admin: Plugin Management](./11-admin.md#115-system-plugin-management) |
| + | |
| + | --- |
| + | |
| + | ## Overview |
| + | |
| + | | Property | Value | |
| + | |----------|-------| |
| + | | **Plugin Type** | Integration | |
| + | | **Author** | FilaMan | |
| + | | **Source** | [Fire-Devils/filaman-plugins](https://github.com/Fire-Devils/filaman-plugins) (Registry) | |
| + | | **API Path** | `/spoolman/api/v1/` | |
| + | | **Capabilities** | Spoolman API v1 compatibility, CRUD operations, CSV/JSON export, IP access control | |
| + | |
| + | --- |
| + | |
| + | ## What is Spoolman? |
| + | |
| + | [Spoolman](https://github.com/Donkie/Spoolman) is a widely used open-source filament management system for 3D printing. Many tools in the 3D printing ecosystem (e.g. Moonraker, OctoPrint) support the Spoolman API for tracking filament usage and managing spools. |
| + | |
| + | With this plugin, FilaMan can be used instead of Spoolman without needing to reconfigure external tools — they simply speak the same API. |
| + | |
| + | --- |
| + | |
| + | ## Configuring External Tools |
| + | |
| + | ### Moonraker (Klipper) |
| + | |
| + | Add the following to your `moonraker.conf`: |
| + | |
| + | ```ini |
| + | [spoolman] |
| + | server: http://<filaman-host>:8000/spoolman |
| + | ``` |
| + | |
| + | Replace `<filaman-host>` with the IP address or hostname of your FilaMan installation. |
| + | |
| + | ### OctoPrint |
| + | |
| + | In the Spoolman plugin settings of OctoPrint, use the URL: |
| + | |
| + | ``` |
| + | http://<filaman-host>:8000/spoolman |
| + | ``` |
| + | |
| + | ### Other Tools |
| + | |
| + | Any tool that supports the Spoolman API can be configured with the same URL: |
| + | |
| + | ``` |
| + | http://<filaman-host>:8000/spoolman/api/v1/ |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## IP Access Control |
| + | |
| + | The plugin provides **IP-based access control** that lets you restrict which devices are allowed to access the Spoolman API. |
| + | |
| + | ### Settings |
| + | |
| + | You can find the settings on the plugin page in the admin area under **Spoolman API**. |
| + | |
| + | | Setting | Description | |
| + | |---------|-------------| |
| + | | **IP filter enabled** | Toggles IP access control on/off. **Disabled** by default (all IPs allowed). | |
| + | | **Allowed IPs** | List of allowed IP addresses or ranges | |
| + | |
| + | ### Supported IP Formats |
| + | |
| + | | Format | Example | Description | |
| + | |--------|---------|-------------| |
| + | | **Wildcard** | `*` | Allow all IPs | |
| + | | **Single IP** | `192.168.1.5` | Exact IP address | |
| + | | **CIDR range** | `192.168.1.0/24` | Entire subnet | |
| + | | **Large range** | `10.0.0.0/8` | Large network range | |
| + | |
| + | > **Note:** When the IP filter is enabled and a non-allowed IP attempts access, the request is rejected with HTTP 403 (Forbidden). |
| + | |
| + | --- |
| + | |
| + | ## API Endpoints |
| + | |
| + | All Spoolman endpoints are available under the path `/spoolman/api/v1/`: |
| + | |
| + | ### System |
| + | |
| + | | Method | Path | Description | |
| + | |--------|------|-------------| |
| + | | GET | `/info` | API information | |
| + | | GET | `/health` | Health check | |
| + | |
| + | ### Vendors |
| + | |
| + | | Method | Path | Description | |
| + | |--------|------|-------------| |
| + | | GET | `/vendor` | List all vendors | |
| + | | POST | `/vendor` | Create new vendor | |
| + | | GET | `/vendor/{id}` | Get vendor | |
| + | | PATCH | `/vendor/{id}` | Update vendor | |
| + | | DELETE | `/vendor/{id}` | Delete vendor | |
| + | |
| + | ### Filaments |
| + | |
| + | | Method | Path | Description | |
| + | |--------|------|-------------| |
| + | | GET | `/filament` | List all filaments | |
| + | | POST | `/filament` | Create new filament | |
| + | | GET | `/filament/{id}` | Get filament | |
| + | | PATCH | `/filament/{id}` | Update filament | |
| + | | DELETE | `/filament/{id}` | Delete filament | |
| + | |
| + | ### Spools |
| + | |
| + | | Method | Path | Description | |
| + | |--------|------|-------------| |
| + | | GET | `/spool` | List all spools | |
| + | | POST | `/spool` | Create new spool | |
| + | | GET | `/spool/{id}` | Get spool | |
| + | | PATCH | `/spool/{id}` | Update spool | |
| + | | DELETE | `/spool/{id}` | Delete spool | |
| + | | PUT | `/spool/{id}/use` | Use filament from spool | |
| + | | PUT | `/spool/{id}/measure` | Measure spool weight | |
| + | |
| + | ### Additional Endpoints |
| + | |
| + | | Method | Path | Description | |
| + | |--------|------|-------------| |
| + | | GET | `/material` | List material types | |
| + | | GET | `/location` | List locations | |
| + | | PATCH | `/location/{name}` | Rename location | |
| + | | GET | `/setting/{key}` | Get setting | |
| + | | POST | `/setting/{key}` | Set setting | |
| + | |
| + | ### Export |
| + | |
| + | | Method | Path | Description | |
| + | |--------|------|-------------| |
| + | | GET | `/export/spools` | Export spools (CSV/JSON) | |
| + | | GET | `/export/filaments` | Export filaments (CSV/JSON) | |
| + | | GET | `/export/vendors` | Export vendors (CSV/JSON) | |
| + | | POST | `/backup` | Create backup | |
| + | |
| + | --- |
| + | |
| + | ## Data Mapping |
| + | |
| + | Spoolman API terms are mapped internally to the FilaMan data model: |
| + | |
| + | | Spoolman Term | FilaMan Equivalent | |
| + | |--------------|-------------------| |
| + | | Vendor | Manufacturer | |
| + | | Filament | Filament | |
| + | | Spool | Spool | |
| + | | Location | Location | |
| + | | Extra Fields | Custom Fields | |
| + | |
| + | --- |
| + | |
| + | ← [Back: Plugin: SpoolmanDB Import](./15-plugin-spoolmandb.md) | [Next: More Plugins →](#) |