20. Installation auf dem Raspberry Pi

Diese Anleitung richtet sich an absolute Einsteiger und erklärt Schritt für Schritt, wie du FilaMan auf einem Raspberry Pi installierst. Es werden keine Vorkenntnisse vorausgesetzt -- nur ein Raspberry Pi, ein PC und etwas Geduld.

20.1 Was du brauchst (Voraussetzungen)

Hardware

Software (auf deinem PC)

• Raspberry Pi Imager -- zum Beschreiben der SD-Karte (Download hier)
• SSH-Client -- zum Verbinden mit dem Pi:
  • Windows: PuTTY oder das eingebaute Windows-Terminal (ab Windows 10)
  • macOS / Linux: Terminal (ist bereits vorinstalliert)

Netzwerk

• Der Raspberry Pi und dein PC müssen sich im selben Netzwerk befinden (gleiches WLAN oder am selben Router per Kabel)

20.2 Raspberry Pi OS installieren

Das Betriebssystem für den Raspberry Pi wird auf eine microSD-Karte geschrieben. Das geht am einfachsten mit dem Raspberry Pi Imager.

Schritt 1: Raspberry Pi Imager herunterladen

Lade den Imager von der offiziellen Webseite herunter und installiere ihn auf deinem PC:

https://www.raspberrypi.com/software/

Schritt 2: Imager starten und konfigurieren

1. Stecke die microSD-Karte in deinen PC (ggf. mit SD-Kartenleser)

2. Öffne den Raspberry Pi Imager

3. Klicke auf „Gerät wählen" und wähle dein Raspberry Pi Modell aus

4. Klicke auf „OS wählen" und wähle:

   • Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit)

   Warum „Lite"? Die Lite-Variante hat keine grafische Oberfläche und verbraucht weniger Ressourcen. FilaMan ist eine Web-Anwendung -- du bedienst sie über den Browser deines PCs, nicht am Pi selbst.

5. Klicke auf „SD-Karte wählen" und wähle deine microSD-Karte aus

   Achtung: Alle Daten auf der SD-Karte werden gelöscht!

Schritt 3: Erweiterte Einstellungen konfigurieren

Klicke auf „Weiter" und dann auf „Einstellungen bearbeiten". Hier konfigurierst du wichtige Grundeinstellungen:

Reiter „Allgemein":

Reiter „Dienste":

• Setze den Haken bei „SSH aktivieren"
• Wähle „Passwort zur Authentifizierung verwenden"

Was ist SSH? SSH (Secure Shell) ermöglicht es dir, den Raspberry Pi von deinem PC aus über die Kommandozeile fernzusteuern -- ohne dass ein Bildschirm am Pi angeschlossen sein muss.

Klicke auf „Speichern" und dann auf „Ja", um das OS auf die SD-Karte zu schreiben.

Schritt 4: Raspberry Pi starten

1. Warte bis der Schreibvorgang abgeschlossen ist
2. Entferne die microSD-Karte sicher vom PC
3. Stecke die microSD-Karte in den Raspberry Pi
4. Schließe das Netzwerkkabel an (falls du LAN verwendest)
5. Schließe das Netzteil an -- der Pi startet automatisch
6. Warte ca. 1--2 Minuten, bis der Pi vollständig hochgefahren ist

20.3 Mit dem Raspberry Pi verbinden (SSH)

Jetzt verbindest du dich von deinem PC aus mit dem Raspberry Pi.

IP-Adresse herausfinden

Du brauchst die IP-Adresse deines Raspberry Pi. Es gibt mehrere Möglichkeiten:

Option A: Über den Hostnamen (einfachste Methode)

Wenn du den Hostnamen filaman eingestellt hast, versuche:

ping filaman.local

Die Antwort zeigt dir die IP-Adresse (z. B. 192.168.1.42).

Option B: Im Router nachschauen

1. Öffne die Weboberfläche deines Routers (meist 192.168.1.1 oder 192.168.178.1 bei Fritz!Box)
2. Suche in der Geräteliste nach „filaman" oder „raspberrypi"
3. Notiere die angezeigte IP-Adresse

Option C: Netzwerk scannen

Auf deinem PC kannst du alternativ folgenden Befehl nutzen:

# macOS / Linux:
arp -a | grep raspberry

# Windows (PowerShell):
arp -a

SSH-Verbindung herstellen

macOS / Linux (Terminal):

ssh pi@filaman.local

Oder mit der IP-Adresse:

ssh pi@192.168.1.42

Ersetze 192.168.1.42 durch die tatsächliche IP-Adresse deines Pi.

Beim ersten Verbinden wirst du gefragt, ob du dem Host vertrauen möchtest. Tippe yes ein und drücke Enter. Gib dann das Passwort ein, das du im Raspberry Pi Imager festgelegt hast.

Windows (PuTTY):

1. Öffne PuTTY
2. Trage bei Host Name ein: filaman.local (oder die IP-Adresse)
3. Port: 22
4. Klicke auf „Open"
5. Benutzername: pi
6. Passwort: Dein gewähltes Passwort

Tipp: Ab Windows 10 kannst du auch einfach das Windows Terminal oder die Eingabeaufforderung verwenden und denselben ssh-Befehl wie bei macOS/Linux nutzen.

Wenn die Verbindung steht, siehst du eine Kommandozeile wie:

pi@filaman:~ $

Du bist jetzt auf dem Raspberry Pi eingeloggt.

20.4 System aktualisieren

Bevor wir FilaMan installieren, bringen wir das Betriebssystem auf den neuesten Stand:

sudo apt update && sudo apt upgrade -y

Was passiert hier?

• sudo = Befehl mit Administrator-Rechten ausführen
• apt update = Liste der verfügbaren Software-Pakete aktualisieren
• apt upgrade -y = Alle Pakete auf die neueste Version aktualisieren (-y = ohne Nachfrage bestätigen)

Das kann einige Minuten dauern. Warte, bis der Vorgang abgeschlossen ist.

20.5 Docker installieren

FilaMan läuft in einem Docker-Container. Docker ist eine Software, die Anwendungen in abgeschotteten Paketen (sogenannten Containern) laufen lässt. Das hat den Vorteil, dass du dir keine Gedanken über Abhängigkeiten oder Konfiguration machen musst -- alles ist im Container enthalten.

Docker installieren

Führe folgenden Befehl aus:

curl -fsSL https://get.docker.com | sh

Dieser Befehl lädt das offizielle Docker-Installationsskript herunter und führt es aus. Die Installation dauert ca. 2--5 Minuten.

Deinen Benutzer zur Docker-Gruppe hinzufügen

Damit du Docker-Befehle ohne sudo ausführen kannst:

sudo usermod -aG docker pi

Ersetze pi durch deinen Benutzernamen, falls du einen anderen gewählt hast.

Abmelden und neu anmelden

Damit die Gruppenänderung wirksam wird, musst du dich einmal ab- und wieder anmelden:

exit

Verbinde dich dann erneut per SSH:

ssh pi@filaman.local

Installation überprüfen

Prüfe, ob Docker korrekt installiert ist:

docker --version

Erwartete Ausgabe (Versionsnummer kann abweichen):

Docker version 27.x.x, build xxxxxxx

Prüfe auch Docker Compose:

docker compose version

Erwartete Ausgabe:

Docker Compose version v2.x.x

Wenn beide Befehle eine Versionsnummer anzeigen, ist Docker fertig installiert.

20.6 FilaMan einrichten

Jetzt erstellen wir die Konfigurationsdateien für FilaMan.

Verzeichnis erstellen

mkdir ~/filaman && cd ~/filaman

Sichere Schlüssel generieren

FilaMan benötigt zwei geheime Schlüssel für die Sicherheit. Generiere diese mit folgendem Befehl:

echo "SECRET_KEY: $(openssl rand -hex 32)"
echo "CSRF_SECRET_KEY: $(openssl rand -hex 32)"

Wichtig: Kopiere die beiden ausgegebenen Schlüssel und bewahre sie auf. Du brauchst sie gleich für die .env-Datei.

Die Ausgabe sieht ungefähr so aus:

SECRET_KEY: 3a7f2b1e9c4d8f6a5e2b1c7d9f3a8e6b4c1d7f2a9e5b3c8d6f4a1e7b2c9d5f
CSRF_SECRET_KEY: 8e2f4a6c1d9b7e3f5a2c8d4b6e1f9a7c3d5b8e2f4a6c1d9b7e3f5a2c8d4b6e

Konfigurationsdatei erstellen (.env)

Erstelle die .env-Datei mit den Einstellungen für FilaMan:

nano .env

Füge folgenden Inhalt ein und passe die markierten Stellen an:

env
# ===========================================
# Datenbank-Konfiguration
# ===========================================
# SQLite (Standard - empfohlen für Raspberry Pi)
DATABASE_URL=sqlite+aiosqlite:////app/data/filaman.db

# ===========================================
# Sicherheit
# ===========================================
# WICHTIG: Ersetze diese durch deine generierten Schlüssel!
SECRET_KEY=HIER_DEINEN_GENERIERTEN_SECRET_KEY_EINFUEGEN
CSRF_SECRET_KEY=HIER_DEINEN_GENERIERTEN_CSRF_SECRET_KEY_EINFUEGEN

# ===========================================
# Administrator-Konto
# ===========================================
# Diese Daten werden beim ersten Start zum Erstellen des Admin-Kontos verwendet
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=MeinSicheresPasswort123!
ADMIN_DISPLAY_NAME=Admin
ADMIN_LANGUAGE=de
ADMIN_SUPERADMIN=true

# ===========================================
# Anwendungseinstellungen
# ===========================================
DEBUG=false
CORS_ORIGINS=*
PORT=8000

# ===========================================
# Logging
# ===========================================
LOG_LEVEL=INFO
LOG_FORMAT=text

Erklärung der Einstellungen:

Speichere die Datei mit Strg+O, Enter und schließe den Editor mit Strg+X.

Docker Compose-Datei erstellen

nano docker-compose.yml

Füge folgenden Inhalt ein:

services:
  filaman-system-app:
    image: ghcr.io/fire-devils/filaman-system:latest
    container_name: filaman-system-app
    env_file:
      - .env
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - SECRET_KEY=${SECRET_KEY}
      - CSRF_SECRET_KEY=${CSRF_SECRET_KEY}
      - DEBUG=${DEBUG}
      - CORS_ORIGINS=${CORS_ORIGINS}
      - ADMIN_EMAIL=${ADMIN_EMAIL}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - ADMIN_DISPLAY_NAME=${ADMIN_DISPLAY_NAME}
      - ADMIN_LANGUAGE=${ADMIN_LANGUAGE}
      - ADMIN_SUPERADMIN=${ADMIN_SUPERADMIN}
    volumes:
      - filaman_data:/app/data
    restart: unless-stopped
    ports:
      - "${PORT}:8000"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3

volumes:
  filaman_data:

Speichere die Datei mit Strg+O, Enter und schließe den Editor mit Strg+X.

20.7 FilaMan starten

Jetzt ist alles vorbereitet. Starte FilaMan mit:

docker compose up -d

Was passiert hier?

• docker compose up = Startet die in docker-compose.yml definierten Container
• -d = Im Hintergrund (detached) laufen lassen

Beim ersten Start wird das Docker-Image heruntergeladen (ca. 200--400 MB). Das kann je nach Internetverbindung einige Minuten dauern.

Logs prüfen

Schau dir die Logs an, um zu überprüfen, ob alles korrekt startet:

docker compose logs -f

Du solltest ungefähr folgende Ausgaben sehen:

filaman-system-app  | Checking for database migrations...
filaman-system-app  | Running migrations...
filaman-system-app  | Database migrations complete.
filaman-system-app  | Starting nginx...

Drücke Strg+C, um die Log-Ansicht zu beenden (der Container läuft im Hintergrund weiter).

Status prüfen

docker compose ps

Wenn alles funktioniert, siehst du:

NAME                   STATUS                    PORTS
filaman-system-app     Up X minutes (healthy)    0.0.0.0:8000->8000/tcp

Der Status sollte nach ca. 30 Sekunden auf (healthy) wechseln.

20.8 FilaMan im Browser aufrufen

FilaMan ist jetzt bereit! Öffne einen Browser auf deinem PC und rufe folgende Adresse auf:

http://filaman.local:8000

Oder verwende die IP-Adresse deines Raspberry Pi:

http://192.168.1.42:8000

Tipp: Die IP-Adresse deines Pi findest du mit folgendem Befehl (auf dem Pi per SSH):

hostname -I

Erste Anmeldung

Du siehst die Login-Seite von FilaMan. Melde dich mit den Zugangsdaten an, die du in der .env-Datei festgelegt hast:

• E-Mail: Die ADMIN_EMAIL aus deiner .env (z. B. admin@example.com)
• Passwort: Das ADMIN_PASSWORD aus deiner .env

Nach der Anmeldung siehst du das Dashboard -- die Startseite von FilaMan.

Ausführliche Informationen zur Anmeldung findest du in der Dokumentation: Anmeldung (Login)

20.9 Erste Schritte nach der Installation

Nachdem FilaMan läuft, empfiehlt es sich, die Daten in folgender Reihenfolge anzulegen:

Tipp: Du kannst alternativ auch Filamente aus der SpoolmanDB importieren, anstatt alles manuell anzulegen. Installiere dazu das SpoolmanDB-Plugin (siehe nächstes Kapitel).

20.10 Plugins installieren

FilaMan lässt sich über Plugins erweitern. Die Installation erfolgt bequem über die Weboberfläche.

Plugin installieren

1. Gehe zu Admin Panel → System
2. Klicke auf „Install Plugin"
3. Wähle im Dropdown „Install from Registry" das gewünschte Plugin aus
4. Klicke auf „Install Plugin"
5. Das Plugin wird automatisch heruntergeladen und installiert

Verfügbare Plugins

Ausführliche Informationen zur Plugin-Verwaltung: Admin-Bereich

20.11 FilaMan aktualisieren

Um FilaMan auf die neueste Version zu aktualisieren, führe auf dem Raspberry Pi folgende Befehle aus:

cd ~/filaman
docker compose pull
docker compose up -d

Was passiert beim Update?

1. docker compose pull lädt die neueste Version des Docker-Images herunter
2. docker compose up -d startet den Container mit der neuen Version neu
3. Beim Start wird automatisch ein Backup der Datenbank erstellt
4. Anschließend werden automatisch alle nötigen Datenbank-Migrationen durchgeführt

Deine Daten bleiben vollständig erhalten!

20.12 Nützliche Befehle

Hier eine Übersicht der wichtigsten Docker-Befehle für den täglichen Betrieb:

Container verwalten

# In das FilaMan-Verzeichnis wechseln
cd ~/filaman

# Container stoppen
docker compose stop

# Container starten
docker compose start

# Container neu starten
docker compose restart

# Container stoppen und entfernen (Daten bleiben erhalten!)
docker compose down

# Container erstellen und starten
docker compose up -d

Logs ansehen

# Alle Logs anzeigen (fortlaufend)
docker compose logs -f

# Nur die letzten 100 Zeilen
docker compose logs --tail 100

# Logs seit einem bestimmten Zeitpunkt
docker compose logs --since 1h

Container-Status prüfen

# Status aller Container
docker compose ps

# Detaillierte Container-Infos
docker inspect filaman-system-app

Administrator-Passwort zurücksetzen

Falls du dein Passwort vergessen hast:

docker exec -it filaman-system-app python -m app.cli reset-password admin@example.com

Ersetze admin@example.com durch deine tatsächliche Admin-E-Mail-Adresse. Du wirst zweimal nach dem neuen Passwort gefragt.

Daten und Backups

Die FilaMan-Daten werden in einem Docker-Volume gespeichert. Automatische SQLite-Backups werden unter /app/data/backups im Container erstellt.

# Backup-Verzeichnis im Container anzeigen
docker exec filaman-system-app ls -la /app/data/backups/

Backups können auch über die Weboberfläche unter Admin Panel → Database Backup verwaltet werden. Siehe: Datenbank-Backup

20.13 Fehlerbehebung

Container startet nicht

Prüfe die Logs auf Fehlermeldungen:

docker compose logs

Häufige Ursachen:

• Fehlende oder ungültige .env-Datei -- Prüfe ob alle Pflichtfelder gesetzt sind
• Syntaxfehler in docker-compose.yml -- Achte auf korrekte Einrückung (Leerzeichen, keine Tabs)

Port bereits belegt

Falls Port 8000 bereits von einem anderen Dienst verwendet wird:

1. Öffne die .env-Datei:
   nano ~/filaman/.env
   

2. Ändere den Port, z. B.:
   PORT=8080
   

3. Starte den Container neu:
   cd ~/filaman
   docker compose down
   docker compose up -d
   

4. FilaMan ist dann unter http://filaman.local:8080 erreichbar

Zugriff von einem anderen Gerät nicht möglich

• Stelle sicher, dass PC und Raspberry Pi im selben Netzwerk sind
• Verwende die IP-Adresse statt des Hostnamens (http://192.168.x.x:8000)
• Prüfe, ob eine Firewall auf dem Pi den Port blockiert:
  sudo ufw status
  

  Falls aktiv, Port freigeben:
  sudo ufw allow 8000/tcp
  

Passwort vergessen

Siehe Administrator-Passwort zurücksetzen oben oder in der Dokumentation: Tipps & Häufige Fragen

Datenbank-Probleme

Wenn die Datenbank beschädigt ist, kannst du ein Backup wiederherstellen:

1. Über die Weboberfläche: Admin Panel → Database Backup → SQLite-Backups → Restore
2. Oder manuell per Kommandozeile:
   # Verfügbare Backups anzeigen
   docker exec filaman-system-app ls -la /app/data/backups/
   

Detaillierte Informationen zur Backup-Wiederherstellung: Datenbank-Backup

20.14 Weiterführende Links

← Zurück: Plugin: Bambuddy | Zurück zum Inhaltsverzeichnis

Diese Anleitung wurde für FilaMan erstellt. Für technische Fragen oder Probleme wenden Sie sich an Ihren Systemadministrator.