Den App-Build-Worker betreiben

Das Frontend einer App (React, Svelte oder ein einfacher Quellordner) wird nicht im API-Prozess gebaut. Ein eigener Build-Worker pollt die Warteschlange, holt sich einen Build nach dem anderen, führt vite build aus und meldet das Ergebnis zurück. Diese Seite beschreibt, wie man ihn betreibt.

Er pollt, er läuft nicht einmal durch

Der Worker hat keinen eigenen Ausstiegspfad. Er holt sich einen Build, baut, meldet und holt den nächsten — bis ihm jemand das Stoppsignal gibt. Eine Laufzeit von Wochen ist korrektes Verhalten, kein Leck. Ein Container, dessen Name einen Einmal-Job behauptet, ist ein Container, den der Nächste löscht.

Warum es diese Seite gibt

Am 28.08.2026 fand ein flottenweiter Suchlauf nach verwaisten Containern auf dem Stage-Host einen, der seit 58 Tagen unter dem Namen stage-app-builder-oneshot lief. Er trug kein com.docker.compose.project-Etikett, also gehörte er niemandem und niemand hätte ihn je neu gestartet. Er war eine Entscheidung davon entfernt, als Müll abgeräumt zu werden.

Er war kein Müll. Er war der Build-Worker und tat genau das, wofür er gebaut ist.

Zwei Dinge machten diesen Beinahe-Verlust möglich; diese Seite schließt beide:

1. Der Name log. An oneshot ist bei einem Poller nichts wahr.
2. Sein Ausfall ist unsichtbar. Es gibt keinen Alarm auf „niemand pollt die Build-Warteschlange”. Nimmt man den Worker weg, stauen sich App-Builds einfach: nichts schlägt fehl, nichts alarmiert, und das erste Symptom ist ein Nutzer, der meldet, ein Build „tue nichts”.

Als überwachten Dienst betreiben

Betreibe ihn als Compose-Dienst, nie als handgestartetes docker run. Ein handgestarteter Container überlebt keinen Host-Neustart, trägt kein Projekt-Etikett und ist für jeden, der aufräumt, von Abfall nicht zu unterscheiden.

services:
  supacloud-app-builder:
    image: git.blockworx.tech/blockworx/supacloud-agent-unified:node
    restart: unless-stopped
    environment:
      AGENT_TYPE: app_builder
      SUPACLOUD_API_URL: https://app.example.com
      RUNNER_TOKEN: ${SUPACLOUD_RUNNER_TOKEN}

Benenne ihn nach dem, was er ist. supacloud-app-builder ist der kanonische Name; alles mit oneshot, job oder temp darin ist falsch und lädt zum Löschen ein.

Der Umgebungsvertrag

Variable	Pflicht	Bedeutung
AGENT_TYPE	ja	Muss exakt app_builder sein. Sie wählt den Kurzschluss im Einstiegspunkt des Runners, noch bevor die Harness-Adapter-Registry befragt wird.
SUPACLOUD_API_URL	ja	Basis-URL der SupaCloud-API. Nachlaufende Schrägstriche werden entfernt.
RUNNER_TOKEN	ja	Das Runner-Credential. SUPACLOUD_RUNNER_TOKEN wird als Alias akzeptiert.
BUILD_POLL_INTERVAL_MS	nein	Millisekunden zwischen zwei Abfragen einer leeren Warteschlange. Standard 5000; ein nicht-numerischer oder nicht-positiver Wert fällt auf den Standard zurück, statt zu scheitern.
BUILD_ALLOW_POSTINSTALL	nein	Akzeptiert 1 oder true. Erlaubt npm-postinstall-Skripte während des Builds. Lass sie ungesetzt. Sie ist aus gutem Grund standardmäßig aus: ein postinstall-Skript ist beliebiger Code aus einem Abhängigkeitsbaum.

Setze weder TASK_ID noch TASK_PROMPT. Jeder andere Runner-Modus verlangt sie; dieser ist ausdrücklich ausgenommen, weil er an keine Aufgabe gebunden ist. Sie zu setzen schadet nicht, stellt den Prozess aber falsch dar.

Fehlt SUPACLOUD_API_URL oder RUNNER_TOKEN, beendet sich der Worker sofort mit einer benannten Fehlermeldung, statt still weiterzupollen. restart: unless-stopped ist damit sicher: ein fehlkonfigurierter Worker läuft sichtbar in eine Neustartschleife, statt Arbeit vorzutäuschen.

Mehr als einen betreiben

Der Zugriff auf die Warteschlange läuft transaktional über FOR UPDATE SKIP LOCKED, zwei Worker holen sich also nie denselben Build. Ein zweiter Worker ist damit sicher und zugleich die einfachste Verteidigung gegen den lautlosen Ausfall von oben: mit einem Worker legt sein Verlust alle Builds still, mit zweien hält der Überlebende die Warteschlange in Bewegung.

Skaliere für Redundanz, nicht für Durchsatz

Jeder Worker baut eine App zur Zeit, mehr Worker erhöhen also den Durchsatz. Der Grund für den zweiten ist aber ein anderer: der erste kann unbemerkt sterben.

Prüfen, ob er lebt

Die Gesundheit des Workers ist nicht „der Container läuft” — ein Poller mit falschem Token, der in einer Neustartschleife hängt, sieht zwischen zwei Neustarts betriebsbereit aus. Prüfe stattdessen die Warteschlange:

• Aus der Flotte: Der Container existiert, trägt ein Compose-Projekt-Etikett, und sein Log zeigt Starting unified runner in app_builder mode, gefolgt von Poll-Aktivität statt eines sich wiederholenden Startfehlers.
• Aus dem Produkt: Stoße für eine beliebige App einen Build an und prüfe, ob er den Wartezustand verlässt. Ein Build, der wartet, während die API gesund ist, bedeutet: niemand holt ihn ab.

Fehlersuche

Symptom	Ursache	Behebung
Builds warten endlos, API gesund	Kein Worker läuft, oder alle hängen in der Neustartschleife	Prüfen, ob der Dienst läuft, und seine erste Log-Zeile lesen
Worker endet sofort, SUPACLOUD_API_URL is required	Variable nicht oder leer gesetzt	Setzen; ein nachlaufender Schrägstrich wird entfernt, nicht abgelehnt
Worker endet sofort, RUNNER_TOKEN is required	Weder RUNNER_TOKEN noch SUPACLOUD_RUNNER_TOKEN gesetzt	Eines von beiden setzen
Worker pollt, holt aber nie etwas	Warteschlange ist wirklich leer, oder dem Token fehlt der Zugriff	Einen Build einstellen und das Log beobachten
Container nach Host-Neustart verschwunden	Er war handgestartet, kein Compose-Dienst	Wie oben gezeigt als Dienst betreiben

Verwandt

• Einen Runner sicher einrichten — das Runner-Credential, das dieser Worker verwendet.
• App-Hosting auf eigener Origin — wohin das Artefakt ausgeliefert wird, das dieser Worker erzeugt.