Flux.

Flux installieren

In einer Viertelstunde von null zum ersten Drucker in der App. Gilt für die geschlossene Beta.

1. Was brauchst du?

Ohne Server ausprobieren: Auf dem Anmeldebildschirm der App gibt es „Demo ausprobieren“. Das läuft komplett in der App mit Beispieldaten, ohne Netzwerk. Es wird nichts an echte Geräte gesendet.

Wichtig vorab: Der Server spricht nur unverschlüsseltes HTTP und ist nur fürs Heimnetz gedacht. Gib den Port nicht im Router frei. Für unterwegs: VPN (z. B. Tailscale oder WireGuard) oder ein Reverse Proxy mit HTTPS. Dann zusätzlich FLUX_LOCAL_PAIRING=false in einer .env setzen.

2. Server installieren

Flux wird als fertiges Docker-Image verteilt: ghcr.io/schallerje/flux-server (Tag beta). Quellcode und Build sind nicht nötig.

  1. Ordner anlegen und die folgende Datei als docker-compose.yml darin speichern: 
    # Flux server - self-hosting from the public image (no source code, no build).
#
#   mkdir flux && cd flux
#   (save this file as docker-compose.yml)
#   mkdir -p data && sudo chown 1000:1000 data     # Linux: the container user has UID 1000
#   docker compose up -d
#   docker compose logs flux | grep "Setup token"  # one-time setup token for the first owner
#
# Update: docker compose pull && docker compose up -d
# Beta: only linux/amd64 (x86_64). Raspberry Pi / ARM follows.
# Requires Docker Compose v2.24 or newer. See SELF-HOSTING.md.
services:
  flux:
    image: ghcr.io/schallerje/flux-server:beta
    container_name: flux-backend
    restart: unless-stopped
    ports:
      # host:container - the app inside the container listens on 3020.
      # Reverse proxy on the same machine in front? Bind to loopback only so the plain-HTTP
      # port is not reachable from the network: - "127.0.0.1:${FLUX_PORT:-3021}:3020"
      - "${FLUX_PORT:-3021}:3020"
    volumes:
      - ./data:/app/data
    # Optional settings from .env (APNs, Home Assistant, secrets, ...) are
    # passed through; the file may be absent. The explicit values below win.
    env_file:
      - path: .env
        required: false
    environment:
      PORT: "3020"
      FLUX_DATA_PATH: /app/data
      FLUX_SHADOW_MODE: "false"
      FLUX_ACTIVE_JOBS: "true"
      # true: any client whose connection comes from a private address (typical home-network addresses)
      # may request a one-time pairing code without signing in. Behind a reverse proxy every
      # visitor arrives from the proxy's private address and would look local, so set
      # FLUX_LOCAL_PAIRING=false in .env there (or when Flux is reachable from outside your LAN).
      FLUX_LOCAL_PAIRING: ${FLUX_LOCAL_PAIRING:-true}
    healthcheck:
      test:
        - CMD
        - node
        - -e
        - "fetch('http://127.0.0.1:3020/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3
  2. Nur Linux: Datenordner für den Container-User (UID 1000) beschreibbar machen: 
    mkdir -p data
sudo chown 1000:1000 data
  3. Hinter einem Reverse Proxy oder von außerhalb des LANs erreichbar? Vor dem ersten Start: 
    echo 'FLUX_LOCAL_PAIRING=false' > .env
  4. Starten (keine .env und keine Schlüssel nötig, die werden beim ersten Start erzeugt): 
    docker compose up -d
docker compose ps          # STATUS sollte "healthy" werden
curl http://localhost:3021/health
    Der Server lauscht auf Host-Port 3021 (änderbar mit FLUX_PORT in der .env).
  5. Setup-Token aus dem Log holen: 
    docker compose logs flux | grep "Setup token"
    Er sieht aus wie 7K2QX-9M4VD-BH3TN und verhindert, dass jemand anderes im Netz deinen frischen Server übernimmt.
  6. Im Browser http://<deine-server-ip>:3021/ öffnen (auf dem Server selbst geht auch http://localhost:3021/). Setup-Token eingeben, die Beta-Nutzungsbedingungen bestätigen und „Server übernehmen“ drücken. Dein Browser ist jetzt der Besitzer.
  7. Der Einrichtungsassistent startet. Jeder Schritt lässt sich überspringen und später unter Einstellungen › Allgemein neu starten:
    • Drucker hinzufügen und mit Verbindung testen prüfen. Der Test liest nur den Status, es wird nichts gesendet. Passwörter und Zugangscodes sind nur schreibbar und werden nie wieder angezeigt.
    • Home Assistant (optional): Adresse und Zugriffstoken, dann pro Drucker eine Steckdose. Flux schlägt eine vor und speichert erst nach „Vorschlag übernehmen“.
    • Benachrichtigungen (optional), siehe Abschnitt 4.
    • App koppeln: erzeugt den QR-Code, siehe Abschnitt 3.

Stoppen: docker compose down (die Daten in ./data bleiben). Update: docker compose pull && docker compose up -d.

Backup: Der Ordner data/ enthält deine Schlüssel (data/secrets.json). Behandle Backups wie ein Passwort und poste sie nie in Bugreports. Geht secrets.json verloren, werden alle gekoppelten Geräte abgemeldet.

3. App installieren und koppeln

  1. TestFlight installieren und den Beta-Link öffnen: <TESTFLIGHT-LINK> (erhältst du im Discord-Beta-Kanal).
  2. Der erste Besitzer muss vorher im Webportal eingerichtet sein (siehe Abschnitt 2). Danach koppelst du das iPhone.

Weg A: QR-Code

  1. Im Assistenten bei App koppeln die Adresse deines Servers eintragen, so wie dein iPhone ihn erreicht (nicht localhost), und „Code erzeugen“ drücken.
  2. In der App QR-Code scannen und die Kamera auf den Code im Browser halten (Kamerazugriff erlauben).
  3. Die App fragt „Mit … koppeln?“. Mit „Koppeln“ bestätigen.

Der Code gilt nur kurz und nur einmal. Einen neuen kannst du jederzeit erzeugen.

Weg B: Code von Hand

Serveradresse in der App eingeben und den Einmalcode aus dem Webportal verwenden („Mit Code koppeln“). Das ist auch der Weg, wenn der QR-Scan nicht klappt.

Weitere Geräte

Nach dem ersten Besitzer wird kein Gerät mehr ohne Zustimmung gekoppelt:

  1. Das neue Gerät tippt „Koppeln anfragen“ und zeigt einen 4-stelligen Prüfcode.
  2. Auf einem schon gekoppelten Gerät (Webportal › Geräte › offene Kopplungsanfragen) erscheint die Anfrage mit Gerätename, Adresse und demselben Code. Codes vergleichen, dann Erlauben oder Ablehnen.
  3. Nach der Freigabe erhält das neue Gerät seine Sitzung automatisch. Unbeantwortete Anfragen laufen nach 5 Minuten ab.

Alternativ erzeugt ein gekoppeltes Gerät direkt einen Code für das neue (Webportal › Geräte › „Create a code for a new device“).

Hinter Docker-NAT oder Reverse Proxy sehen alle Geräte wie eine Adresse aus. Nutze dann die Kopplung per Code von einem gekoppelten Gerät.

4. Push-Mitteilungen

Apple-Push braucht einen Schlüssel, der nicht in deinen Server gehört. Deshalb gibt es optional den Flux-Vermittler, der von Jens Schaller betrieben wird und nur mit Einladung nutzbar ist:

  1. Webportal › Einstellungen › Benachrichtigungen › „Push über Flux-Vermittler“.
  2. Einladungscode eintragen: <EINLADUNGSCODE> (erhältst du im Discord-Beta-Kanal). Er wird auf deinem Server gespeichert und nie wieder angezeigt.
  3. Einwilligung ankreuzen und Aktivieren drücken.

Was übertragen wird: Druckername, Jobname, Ereignis (z. B. „Druck fertig“), das Push-Token deines Geräts und eine zufällige Kennung. Bei Kopplungsanfragen zusätzlich Gerätename, Adresse und Prüfcode, bei Druckfotos die Adresse deines Servers. Empfänger ist Jens Schaller als Betreiber, danach Apple. Details: Datenschutz-Hinweis zum Push-Vermittler.

Ohne Vermittler (ohne Einladungscode) unter Einstellungen › Benachrichtigungen:

Ereignisse: Druck fertig, Druckfehler, Pause, Kopplungsanfrage. Mit „Send test“ prüfst du jeden Kanal.

5. Feedback

6. Bekannte Einschränkungen