Eine App bauen und deployen

Eine App ist die Fläche, die andere anfassen. Alles andere in SupaCloud betreibst du; eine App gibst du heraus – ein Link, den eine Kollegin, eine Kundin oder ein Telefon öffnet, um etwas einzureichen und zu sehen, was zurückkam. Apps findest du unter Build → Apps.

Die zwei Dinge, die eine App sein kann

Genau hier stolpern die meisten, denn beides liegt hinter derselben Framework-Auswahl, und die Auswahl benennt den Unterschied nicht.

• Eine Formular-App – der Dateibaum der App enthält nichts außer manifest.yaml. SupaCloud rendert die inputs:, die du im Manifest deklariert hast, als Formular, nimmt eine Einreichung entgegen und startet daraus einen Run. Du schreibst kein HTML. Diese Runtime ist allgemein verfügbar und funktioniert auf jeder Instanz.
• Ein gehostetes Frontend – die App trägt echte Quelldateien, die SupaCloud als Website ausliefert. Das ist entweder eine react- oder svelte-App, die Vite in ein dist/ baut, oder eine plain-App, der du irgendeine Datei über das Manifest hinaus hinzugefügt hast und die unverändert ausgeliefert wird.

Der Framework-Wert allein sagt also noch nicht alles: Eine plain-App mit nur einem Manifest ist eine Formular-App, und dieselbe plain-App wird in dem Moment zum gehosteten Frontend, in dem du eine index.html hinzufügst.

Gehostete Frontends sind standardmäßig aus – prüfe das, bevor du eines baust

Das Ausliefern eines gehosteten Frontends hängt an einem instanzweiten Betreiberschalter, SUPACLOUD_APPS_HOSTED_FRONTEND, und dieser Schalter ist aus, solange deine Instanz-Administration ihn nicht eingeschaltet hat. Die Oberfläche blendet die Deploy-Schaltfläche dabei nicht aus – du erfährst es also, indem du deployst und den Fehler liest, der auf die funktionierende Formular-App und auf die Variable verweist.

Das Erstellen ist nie blockiert: Du kannst eine React- oder Svelte-App auf jeder Instanz anlegen, bearbeiten, speichern, bauen und in der Vorschau ansehen. Gesperrt ist nur die Veröffentlichung unter einer öffentlichen URL. Den Schalter gibt es, weil das Ausliefern eines gebauten Frontends unter einer beliebigen Route ein Build-Image mit relativer Asset-Basis voraussetzt – ohne das stünde eine App online, deren Assets nicht laden.

Umlegen kann ihn nur eine Instanz-Administration. Wenn du ihn brauchst, frag dort nach – und verweise auf App-Hosting auf separater Origin, wo das Auslieferungsmodell und die optionale Härtung beschrieben sind.

Eine App anlegen

1. Öffne Build → Apps und wähle Neue App.

2. Vergib einen Namen (erforderlich, bis zu 200 Zeichen) und optional eine Beschreibung.

3. Wähle ein Framework:

   • Reines HTML – statisches HTML, CSS und JavaScript, kein Build-Schritt. Auch das Framework, das du für eine Formular-App unangetastet lässt.
   • React (Vite) und Svelte (Vite) – Single-Page-Apps, von Vite gebaut.

   Ein Framework, das dein Tarif nicht enthält, wird gesperrt mit einem Upgrade-Link angezeigt, nicht versteckt. Im Free-Tarif ist nur Reines HTML wählbar.

4. Bearbeite manifest.yaml im Editor unter der Auswahl. Das Start-Manifest ist vorbelegt, und das gewählte Framework wird hineingeschrieben. Deklarierst du inputs:, rendert der Bereich Formular daneben sie live mit – du siehst das Formular also entstehen, bevor die App existiert.

5. Wähle App erstellen. Du landest auf der Detailseite der App mit fünf Reitern: Übersicht, Editor, Ausführungen, Ausführen und Einstellungen.

Im Dateibaum arbeiten

Der Reiter Editor ist ein Browser-IDE über dem Dateibaum der App. manifest.yaml ist immer geöffnet und lässt sich weder schließen noch löschen – es ist die maßgebliche Quelle der App, und die auf dem App-Datensatz abgelegte Kopie wird automatisch mitgeführt.

Lege Dateien mit Pfaden relativ zur App-Wurzel an. Jedes Pfadsegment darf Buchstaben, Ziffern, Punkte, Bindestriche und Unterstriche enthalten; . und .. werden abgewiesen, ein doppelter Pfad ebenso. Binäre Assets werden getrennt von Textdateien gespeichert und nicht im Editor geöffnet.

Speichern schreibt Name, Beschreibung und Manifest, legt anschließend jede geänderte Datei ab und löscht jede entfernte. Speichern tut genau das und sonst nichts – es baut nicht und es deployt nicht. Das sind eigene, bewusste Aktionen.

Welche Vorschau du bekommst, hängt am Framework

Der Bereich neben dem Editor zeigt eine plain-App sofort aus den Dateien im Browser. Bei einer React- oder Svelte-App gibt es nichts vorzuzeigen, solange der Quellcode nicht kompiliert wurde – deshalb bietet der Bereich dort Bauen & Vorschau an: Er fordert einen Build an, verfolgt ihn und zeigt das Ergebnis anschließend in einem Rahmen.

Der App eine Datenbank geben

Eine App kann ein eigenes Postgres-Schema besitzen. Binde eines, indem du im Manifest eine postgresql-Ressource benennst – über ihren Namen oder ihre UUID:

app_db: workspace_app_db

Beim Speichern legt SupaCloud ein Schema an, das aus app_ und der Id der App ohne Bindestriche besteht, und lässt den Provisioner für Row-Level-Security erneut laufen, damit die Daten der App auf die App isoliert bleiben. Der Reiter Einstellungen zeigt den Schemanamen unter Persistenz – oder teilt dir mit, dass die App keines nutzt. Die Bindung muss auf eine postgresql-Ressource zeigen; die verwaltete Workflow-Datenbank wird abgewiesen, weil ihre Isolation an einem Workflow-Namespace hängt und nicht an einer App.

Pro-App-SQL-Migrationen bleiben der Weg, das Schema weiterzuentwickeln. Sie sind prüfsummengesichert und nur anfügbar: Ist ein Migrationsname einmal angewendet, wird eine Änderung seines Inhalts abgewiesen – registriere stattdessen eine Nachfolgemigration unter neuem Namen. Das Anwenden ist idempotent, ein erneuter Lauf ändert also nichts.

Migrationen sind in der Oberfläche nur lesbar

Die Karte Migrationen im Reiter Einstellungen listet jede Migration mit dem Kennzeichen Angewendet oder Ausstehend und einer Zusammenfassung angewendet von gesamt – aber es gibt keinen Weg, im Browser eine zu verfassen. Migrationen kommen über die API oder über Repo-Sync hinein, das die App als deklaratives Manifest unter apps/ ablegt.

Bauen

Ein Build wird immer ausdrücklich angestoßen – Speichern startet nie einen. Fordere ihn über Bauen & Vorschau im Reiter Editor an oder über den Reiter Builds in der Peek-Schublade der App im Board.

Ein Build ist über den Hash seines Quellbaums inhaltsadressiert: Fragst du denselben unveränderten Baum erneut an, bekommst du den vorhandenen Build zurück statt eines zweiten. Die fünf Zustände sind queued, claimed, building, succeeded und failed. Im Hintergrund installiert der Builder die Abhängigkeiten mit abgeschalteten Lifecycle-Skripten und lässt Vite mit relativer Asset-Basis laufen.

Der Reiter Builds zeigt Status, Artefakt- und Quell-Hash, den Startzeitpunkt und – bei einem gescheiterten Build – die vollständige Fehlermeldung des Builders. Diese Meldung ist die Diagnose; eine eigene Build-Log-Seite gibt es nicht.

Eine plain-App braucht zum Deployen keinen Build. Eine React- oder Svelte-App schon: Sie ohne erfolgreichen Build zu deployen wird abgewiesen.

Deployen

1. Wähle Deploy im Kopf der App (auf dem Telefon in der Aktionsleiste des Reiters Editor).

2. Setze den Route-Pfad – das öffentliche Adresssegment, z. B. my-app – und eine Version. Die Version steht standardmäßig auf latest und bindet damit den jüngsten erfolgreichen Build der App.

3. Wähle den Zugriff. Eine frisch deployte App ist standardmäßig privat:

   • Org-Mitglieder (Standard) – nur angemeldete Mitglieder des Workspace der App können sie öffnen.
   • Öffentlich – jeder mit dem Link. Eine ausdrückliche Freigabe.
   • Passwort – jeder mit Link und Passwort. Setze es unter App-Passwort; beim erneuten Deployen behält ein leer gelassenes Feld das bisherige Passwort.

4. Deploye. Danach zeigt das Fenster die Live-URL der App, den Route-Chip und den Deployment-Verlauf und bietet Undeploy sowie Pausieren/Fortsetzen an.

Wo eine deployte App erreichbar ist

Standardmäßig wird eine gehostete App auf dem Host der Control Plane unter /a/<workspace>/<route-pfad> ausgeliefert – innerhalb einer Content-Security-Policy-Sandbox, die ihr eine opake Origin gibt. Genau darum geht es: Das JavaScript einer App darf niemals als die Person handeln können, die sie deployt hat, und eine opake Origin bedeutet, dass die Seite die Control-Plane-Session nicht erreicht, obwohl sie vom selben Host kommt. Eine Formular-App wird immer hier ausgeliefert.

Eine Instanz-Administration kann weiter gehen und eine separate Inhalts-Domain konfigurieren. Jedes gehostete Deployment bekommt dann seine eigene opake Subdomain auf einer anderen registrierbaren Domain als die Control Plane, womit die Isolation zusätzlich auf der Netzwerk- und Cookie-Ebene greift. Ist das eingerichtet, überlappen sich die beiden Wege absichtlich nicht mehr: Ein gehostetes Frontend wird nur auf seiner Subdomain ausgeliefert und antwortet auf dem Pfad mit 404, während eine Formular-App auf dem Pfad bleibt und auf einer Subdomain mit 404 antwortet. Das einzurichten ist Betreiberarbeit – siehe App-Hosting auf separater Origin.

Auf der Standard-Route sind nur Dokumente zugriffsgeschützt

Wird eine App auf dem Pfad der Control Plane ausgeliefert, greift der oben gewählte Zugriffsmodus auf den HTML-Dokumenten der App und ihren clientseitigen Routen – ihre übrigen statischen Assets werden jedoch ungeschützt ausgeliefert. Das ist Absicht: Die Anfragen der sandboxed App nach ihren eigenen Assets sind seitenübergreifend, ein Cookie-basierter Schutz würde also den Seitenaufbau für das berechtigte Mitglied zerstören.

Die praktische Regel lautet deshalb: Liefere niemals mitgliederinterne Daten als statische Datei in einer App aus – kein data.json, kein exportiertes CSV im Baum. Hole solche Daten zur Laufzeit über das Backend der App.

Das App-API-Token

Eine deployte App muss manchmal zu SupaCloud zurückrufen – um einen Run von sich selbst zu starten oder eine ihrer deklarierten Backend-Funktionen aufzurufen. Genau dafür gibt es das App-API-Token im Reiter Übersicht.

Erzeuge es mit App-API-Token generieren (nur Workspace-Administration, und erst wenn die App tatsächlich deployt ist). Der Klartextwert scwa_… wird genau einmal angezeigt – der Server behält nur seinen Hash –, kopiere ihn also sofort. Ein neues Token macht das vorherige unmittelbar ungültig, und Token widerrufen entfernt es ganz.

Nur serverseitig

Sende es als Authorization: Bearer-Header von einem Server, den du kontrollierst. Bette es niemals in das Frontend-Bundle der App ein: Ein gehostetes Frontend besteht aus öffentlichen Bytes, ein dort eingefügtes Token ist also ein veröffentlichtes Token. Die Seite der App selbst braucht es nicht – die Browserseite erhält ein eigenes, kurzlebiges Credential pro Anfrage.

Kontingente, auf die du triffst

Apps werden pro Tarif bemessen, und die Zahlen greifen früher, als man erwartet.

Grenze	Free	Pro	Enterprise
Apps	1	5	unbegrenzt
Gleichzeitig deployt	1	5	unbegrenzt
Speicher	50 MB	500 MB	unbegrenzt
Build-Minuten pro Monat	0	60	unbegrenzt
Bandbreite pro Monat	1 GB	25 GB	unbegrenzt
React-/Svelte-Frameworks	nicht enthalten	enthalten	enthalten

Ein Free-Workspace bekommt also genau eine plain-App und kann überhaupt nicht bauen – was in sich stimmig ist, denn die Frameworks, die einen Build brauchen, sind ebenfalls nicht enthalten. Das erneute Deployen einer bereits laufenden App zählt nie gegen die Grenze der gleichzeitig deployten Apps, das Umhängen einer Route ist also immer erlaubt. Der aktuelle Speicherverbrauch steht in der Fußzeile des Boards und im Deploy-Fenster.

Zusätzlich liegt jeder App-Endpunkt hinter der App-Berechtigung des Workspace – ein Tarif ohne sie sieht die Fläche abweisen, statt dass die Zahlen greifen. Nichts davon hängt an der Edition: Eine unternehmenslizenzierte, selbst gehostete Instanz bekommt schlicht die unbegrenzte Spalte.

An andere ausliefern

Eine App lässt sich im Marktplatz veröffentlichen, und ihr vollständiger Quellbaum reist im Eintrag mit – sie installiert sich also auf einer nackten Instanz, ohne dass irgendwo etwas nachgeladen werden müsste. Eine App mit nichts als einem Manifest wird als Eintrag abgewiesen; veröffentliche eine, die echten Quellcode trägt.

Die meisten nützlichen Produkte sind allerdings nicht ein einzelnes Primitiv. Braucht deine App einen Workflow dahinter, veröffentliche beides als Paket, damit eine Installation das Ganze bringt – siehe Ein Marktplatz-Paket veröffentlichen.

Siehe auch

• Runs und Tasks – was aus einer App-Einreichung wird.
• Ein Skript schreiben und ausführen – der andere Build-Reiter mit einem Browser-IDE.
• Eine Custom-Verbindung anlegen – die postgresql-Ressource anlegen, die eine App als Datenbank bindet.
• App-Hosting auf separater Origin – die Betreiberseite des Auslieferns gehosteter Frontends.