FilaDex

Filament-Lagerverwaltung für den 3D-Druck — selbst gehostet.

FilaDex bildet dein physisches Filamentlager digital ab: welche Rolle hast du, wie viel ist noch drauf, mit welchen Einstellungen druckst du sie, wann wurde sie zuletzt getrocknet, was hat sie gekostet. Dazu kannst du Freunden Lese-Zugriff auf deinen Bestand geben, damit sie sehen, ob du eine bestimmte Farbe da hast — und sich etwas ausleihen können.

📖 Alle Anleitungen: docs/ — Installation, Etiketten, Updates, Freigaben, Entwicklung, Stolperfallen.

Was FilaDex kann

• 📦 Bestand im Blick — Rollen mit Hersteller, Material, Farbe, Standort und Füllstand; als Kachel- oder Tabellenansicht, mit Filtern über Material, Farbe, Status und Lagerort.
• 🔦 Transmissionsdistanz je Rolle — der TD-Wert vom Messgerät (TD-1/TD1s) gehört neben den Farbcode, nicht ans Material: Schwarz und Weiß derselben Sorte liegen weit auseinander. Für Farbverlaufsdrucke mit HueForge und ähnlichen Programmen.
• 🛒 Nachbestellen mit einem Klick — an jeder Rolle lässt sich der Shop-Link hinterlegen. Er erscheint auf der Detailseite und beim Dashboard-Hinweis „bald leer“, also genau dann, wenn er gebraucht wird.
• ⚖️ Verbrauch buchen in Sekunden — in Gramm, in Metern oder als neuer Gesamtrest von der Waage. Die Restmenge wird immer aus der Historie berechnet, nie separat gespeichert.
• 💧 Trocknungs-Log mit Ampel — Temperatur und Dauer aus der Materialart vorbelegt, „zuletzt getrocknet vor X Tagen“ auf jeder Kachel.
• 🏷️ Etiketten mit QR-Code — millimetergenaues PDF für jeden Drucker, dazu optional Direktdruck über den DYMO Connect Web Service. QR scannen führt direkt zur Rolle.
• 🧭 Filament finden — sag, wofür du druckst (draußen, mechanisch belastet, flexibel …), FilaDex sortiert deinen Bestand nach Eignung, begründet jede Einordnung und nennt dazu das Material, das eigentlich richtig wäre.
• 👥 Freigaben und Ausleihe — Freunden lesenden Zugriff geben, ihren Bestand nach Farben durchsuchen, Ausleihen anfragen und zu reinen Materialkosten abrechnen.
• 📱 PWA — auf dem Handy installierbar, Dark Mode, untere Tab-Navigation.
• 🔄 Selbst-Update — Update-Kanäle stable/beta, Update aus der Weboberfläche mit Live-Log, automatischem DB-Backup und Rollback. Ohne Docker-Socket im Anwendungscontainer.
• 💾 Export und Import — JSON mit Historie, CSV für Tabellenkalkulationen, ZIP-Vollsicherung; CSV-Import mit Spaltenzuordnung für den Umzug aus einer gewachsenen Excel-Liste.

Technik

Python 3.12 mit FastAPI und SQLModel, React 18 mit TypeScript und Tailwind, PostgreSQL 17 — alles in zwei Containern, die docker compose zusammen startet. Für den lokalen Testbetrieb reicht SQLite, dafür braucht es weder Server noch Container.

Installation

Ein Befehl auf Ubuntu 22.04/24.04 oder Debian 12/13:

curl -fsSL https://git.hippler.one/AxonByteDev/FilaDex/raw/branch/main/scripts/install.sh -o install.sh && sudo bash install.sh

Wer erst hineinsehen möchte, schiebt LESSCHARSET=utf-8 less install.sh && vor das sudo.

Der Installer richtet Docker, einen eigenen Systembenutzer, die systemd-Dienste und den Update-Watcher ein. Er ist idempotent — mehrfaches Ausführen macht nichts kaputt.

Von Hand geht es auch:

git clone https://git.hippler.one/AxonByteDev/FilaDex.git && cd FilaDex && cp .env.example .env && sed -i "s/^SECRET_KEY=.*/SECRET_KEY=$(openssl rand -hex 32)/" .env && mkdir -p data && APP_VERSION=$(git describe --tags --always | sed 's/^v//') docker compose up -d --build

FilaDex ist danach unter http://<IP-des-Servers>:8420 erreichbar — der Port gehört zur Adresse. Beim ersten Aufruf führt dich der Setup-Assistent durch das Anlegen des ersten Admin-Kontos; es gibt bewusst kein fest verdrahtetes Standardpasswort.

Zwei Dinge, die du danach einstellen solltest

1. Öffentliche URL setzen (Einstellungen → public_base_url). Der Container kennt seine Außenadresse nicht. Ohne diese Einstellung zeigen alle gedruckten QR-Codes auf eine interne Adresse und sind vom Handy aus nutzlos.
2. HTTPS über einen Reverse Proxy. Der Kamera-Scanner braucht getUserMedia, und das verweigern Browser auf unverschlüsselten Origins (Ausnahme: localhost). Über http://192.168.x.x:8420 bleibt die Kamera stumm — das ist kein Fehler von FilaDex.

Erst mal ausprobieren

Vor der Installation auf dem Server lässt sich FilaDex mit einem Befehl lokal starten — das Skript richtet Python-Umgebung und Abhängigkeiten selbst ein:

./scripts/dev.sh --beispieldaten

Danach ist FilaDex über zwei Adressen erreichbar, gefüllt mit einem Testbestand: zwölf Rollen, ein Jahr Verbrauchshistorie, Trocknungsprotokolle, ein zweites Konto mit Freigabe und eine offene Ausleihe.

Adresse
http://localhost:5173	Auf dem eigenen Rechner. Nur hier funktioniert der Kamera-Scanner, weil Browser localhost wie eine verschlüsselte Verbindung behandeln.
http://<IP-des-Rechners>:5173	Von jedem Gerät im selben Netz — zum Ausprobieren der Bedienung am Handy. Die Kamera bleibt dort stumm; dafür braucht es HTTPS.

Das Skript nennt beim Start beide Adressen.

./scripts/dev.sh             nur starten, ohne Testdaten
./scripts/dev.sh --docker    im Container, genau wie auf dem Server
./scripts/dev.sh --nur-lokal nur auf diesem Rechner erreichbar
./scripts/dev.sh --reset     Testdaten verwerfen

Beim Start räumt das Skript Reste eines früheren Laufs selbst weg. Zum Beenden von Hand:

./scripts/stop.sh                      Container und Entwicklungsprozesse beenden
./scripts/stop.sh --docker-neustart    zusätzlich Docker Desktop neu starten

Den Neustart braucht es, wenn Docker Desktop beim Stoppen ECONNREFUSED … backend.sock meldet: Dann ist der Docker-Daemon abgestürzt und die Oberfläche sucht einen Dienst, den es nicht mehr gibt.

Die Testdaten liegen unter data/dev/ und sind von einer echten Installation getrennt.

Entwicklung

./scripts/dev.sh startet Backend und Oberfläche mit automatischem Neuladen. Von Hand geht es auch:

uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -r requirements-dev.txt && .venv/bin/uvicorn backend.main:app --reload --port 8420

cd frontend && npm install && npm run dev

Vor jedem Commit laufen alle Prüfungen lokal — es gibt keinen CI-Runner:

./scripts/check.sh

Oder von Hand als Einzeiler:

.venv/bin/ruff check . && .venv/bin/python -m pytest && cd frontend && npx tsc --noEmit && npx eslint . && npm run build

Version

Die Versionsnummer kommt ausschließlich aus dem Git-Tag, nicht aus einer eingecheckten Datei:

• Beim Docker-Build reicht docker-compose.yml sie als Build-Arg APP_VERSION durch und legt sie als VERSION ins Image.
• Beim Bare-Metal-Betrieb liest backend/version.py sie notfalls selbst über git describe.
• Ohne beides steht dort 0.0.0-dev.

VERSION steht deshalb in .gitignore — sonst kollidiert bei jedem Merge beta → main genau diese Datei.

Dokumentation

Alle Anleitungen liegen als Markdown-Dateien im Ordner docs/ — im Repository lesbar, mit dem Code zusammen versioniert und in jedem Klon dabei:

• Installation — Installer, Docker von Hand, Bare-Metal, Reverse Proxy
• Etiketten-Druck — Größen, PDF-Weg, DYMO Connect, Stolperfallen
• Selbst-Update — Kanäle, Host-Watcher, Rollback, Backups
• Freigaben und Ausleihe — Freunde, Preise, Ausleihablauf
• Entwicklung — Stack, Architektur, API, Release-Workflow
• Stolperfallen — gesammelte Fallen, bevor du sie selbst findest

Lizenz

AGPL-3.0 mit Commons-Clause-Zusatz — kein kommerzieller Weiterverkauf und kein Hosting als Dienstleistung ohne Zustimmung. Der vollständige Text steht in LICENSE.