Rezepte

Ein Rezept ist eine kurze Datei, die Setup sagt, wie eine Software läuft: welche Programme starten, welche Einstellungen du ausfüllst, wo die Daten liegen und woran Setup erkennt, dass alles funktioniert. Wenn du einen Link einfügst, schreibt Setup das Rezept selbst und zeigt es dir, bevor irgendetwas startet. Du musst nie selbst eins schreiben.

Die Datei heißt setup.json. Sie ist einfaches JSON, du kannst sie also lesen, ändern und weitergeben. Sie beschreibt nur, was sich gefahrlos in einer Sandbox ausführen lässt. Es gibt kein Feld, mit dem eine Software an den Rechner kommt, auf dem sie läuft. Das ist Absicht.

Der Rest dieser Seite ist die Referenz für Entwickler und Maintainer.

Woher Rezepte kommen

• Aus einer Analyse. Fügst du einen Link ein, sucht Setup zuerst nach einer setup.json im Repository, dann nach einem kuratierten Rezept im Katalog. Danach liest es Compose-Dateien, Dockerfiles und typische Projektstrukturen. Ergibt das kein sicheres Ergebnis und ist ein Modell eingerichtet, entwirft das Modell ein Rezept. Setup liest das Projekt dabei nur als Daten und führt keinen Code daraus aus.
• Von dir eingefügt. Das Feld auf Start nimmt einen Link, eine Datei oder eine Beschreibung. Füge eine komplette setup.json ein, um sie genau so auszuführen. Fügst du eine Docker-Compose-Datei (mit ihrer .env), docker run-Befehle, einen Image-Namen, ein Dockerfile, Kubernetes-Manifeste oder eine CasaOS-, Umbrel-, Runtipi-, Cosmos- oder Portainer-Definition ein, übersetzt Setup sie in ein Rezept. Unter Erste Schritte stehen alle Arten mit Beispiel.
• Von dir bearbeitet. Vor dem Deployment zeigt der Tab Rezept-JSON das Rezept und lässt dich es ändern. Rezepte aus dem Katalog sind dort schreibgeschützt. Füge eine bearbeitete Kopie auf Start ein, dann gehört sie dir.
• Vom Maintainer. Projekte können eine setup.json in ihrem Repository pflegen. Mehr dazu unter Maintainer.

Ein vollständiges Beispiel

Das ist das Rezept für Umami, eine Web-Analytics-App mit PostgreSQL-Datenbank. Es besteht dieselben Schema- und Regelprüfungen, die Setup auf jedes Rezept anwendet.

{
  "version": 1,
  "slug": "umami",
  "name": "Umami",
  "description": "Cookie-free website analytics with a simple dashboard.",
  "category": "analytics",
  "tags": ["analytics", "privacy", "web"],
  "homepage": "https://umami.is",
  "license": "MIT",
  "source": {
    "kind": "github",
    "url": "https://github.com/umami-software/umami"
  },
  "inputs": [
    {
      "key": "DB_PASSWORD",
      "label": "Database password",
      "type": "secret",
      "generate": "password"
    },
    {
      "key": "APP_SECRET",
      "label": "App secret",
      "type": "secret",
      "generate": "hex32"
    }
  ],
  "services": {
    "db": {
      "image": "postgres:17.11-alpine",
      "env": {
        "POSTGRES_DB": "umami",
        "POSTGRES_USER": "umami",
        "POSTGRES_PASSWORD": "${inputs.DB_PASSWORD}"
      },
      "volumes": [{ "name": "postgres", "path": "/var/lib/postgresql/data" }],
      "healthcheck": {
        "command": [
          "pg_isready",
          "-h",
          "127.0.0.1",
          "-U",
          "umami",
          "-d",
          "umami"
        ]
      },
      "resources": { "cpus": 0.5, "memoryMb": 512 }
    },
    "app": {
      "image": "ghcr.io/umami-software/umami:3.4.0",
      "env": {
        "DATABASE_URL": "postgresql://umami:${inputs.DB_PASSWORD}@${services.db.host}:5432/umami",
        "APP_SECRET": "${inputs.APP_SECRET}"
      },
      "ports": [{ "container": 3000 }],
      "dependsOn": [{ "service": "db", "condition": "healthy" }],
      "resources": { "memoryMb": 512 }
    }
  },
  "expose": { "service": "app", "port": 3000 },
  "checks": {
    "http": { "path": "/api/heartbeat" },
    "startupTimeoutSeconds": 180
  },
  "notes": "Sign in with username `admin` and password `umami`, then change the password under **Settings → Profile**."
}

Beide Passwörter erzeugt Setup, wenn das Feld leer bleibt. Die Datenbank legt ihre Dateien in einem benannten Volume ab, und die App wartet, bis die Datenbank ihren Health-Check besteht. Von außen erreichbar ist nur Port 3000 von app.

Felder auf oberster Ebene

Quelle

"source": {
  "kind": "github",
  "url": "https://github.com/acme/widget",
  "git": { "url": "https://github.com/acme/widget.git", "ref": "v1.4.2", "subdir": "server" }
}

git ist Pflicht, sobald ein Service aus dem Quellcode baut ("build": { "context": "source" }).

Einstellungen (inputs)

Inputs sind die Werte, die jemand beim Start der App angibt, etwa eine Admin-E-Mail-Adresse oder einen API-Schlüssel. Das Dashboard zeigt sie unter Einstellungen.

{
  "key": "ADMIN_EMAIL",
  "label": "Admin email",
  "type": "email",
  "required": true
}

Setup nimmt für jeden Wert in dieser Reihenfolge: was eingegeben wurde, dann default, dann den Generator. Bleibt ein Input mit required leer, startet das Deployment nicht. Ein optionaler Input wird zu einem leeren String.

Danach prüft Setup den Wert gegen seinen Typ. Eine number muss sich als Zahl lesen lassen, ein boolean muss true oder false sein, ein select muss eine seiner options sein, eine url muss eine gültige URL sein und eine email muss aussehen wie name@example.com.

length ändert die Größe: Zeichen bei password, Zufallsbytes bei hex32 und base64-32, also die Zahl, die openssl rand -hex oder -base64 bekommt. Eine App, die einen Hex-Schlüssel mit 32 Zeichen will (openssl rand -hex 16), bekommt "generate": "hex32", "length": 16. uuid hat keine Länge.

Erzeugte Werte speichert Setup mit der App. Sie bleiben über Neustarts und Updates gleich. Werte von secret-Inputs liegen verschlüsselt in der Datenbank.

Verweise in Werten

Werte können auf Inputs, andere Services und die eigene Adresse der App verweisen.

Verweise funktionieren in Werten von env, in command, entrypoint und build.args. Befehle von Health-Checks gehen unverändert durch. $${ schreibt ein wörtliches ${. Ein Verweis auf einen Input oder Service, den es nicht gibt, ist ein Fehler.

Services

services ordnet jedem Service-Namen einen Container zu. Namen beginnen mit einem Kleinbuchstaben und bestehen aus a-z, 0-9 und Bindestrichen, bis 31 Zeichen.

Images und Builds

Pinne Images auf eine Version oder einen Digest. Ein Tag latest, main, master, nightly, edge oder dev oder gar kein Tag löst eine Warnung aus, weil ein Update sonst ändern könnte, was läuft. Image-Referenzen müssen der Registry-Grammatik folgen: keine Leerzeichen, Anführungszeichen oder Shell-Zeichen.

"build": {
  "context": "source",
  "dockerfile": "docker/Dockerfile",
  "target": "production",
  "args": { "NODE_ENV": "production" }
}

Gebaut wird mit BuildKit auf dem Runner. Die Steuerungsebene klont und baut nie etwas.

Ports

"ports": [{ "container": 3000 }]

Von außen erreichbar ist nur der HTTP-Port, den expose nennt, und zwar über den Ingress-Proxy von Setup. Andere Ports erreichen nur die übrigen Services im privaten Netz der App.

Veröffentlichen ist für Homelab-Software gedacht, die etwas anderes als HTTP spricht, etwa DNS oder Gameserver. Ein Runner lehnt das ab, solange sein Betreiber --allow-published-ports nicht eingeschaltet hat (siehe Runner). HTTP-Ports lassen sich nicht veröffentlichen. Sie laufen immer über den Ingress.

Volumes

"volumes": [{ "name": "data", "path": "/app/data" }]

name ist ein Slug, path ein absoluter Pfad im Container ohne ... Volumes sind benannt, gehören zu genau einer App, überstehen Neustarts und Updates und sind Teil jeder Sicherung. Einen Ordner vom Runner-Host einzuhängen geht nicht.

Health-Checks

"healthcheck": {
  "command": ["curl", "-f", "http://127.0.0.1:3000/health"],
  "intervalSeconds": 10,
  "retries": 5
}

Der Befehl muss im Image vorhanden sein. Die Rezepte im Katalog rufen 127.0.0.1 auf statt localhost. Hat ein Image einen eigenen HEALTHCHECK, wartet der Runner auch auf diesen.

Startreihenfolge und One-Shot-Services

"dependsOn": [{ "service": "db", "condition": "healthy" }]

condition ist started (Standard), healthy oder completed. healthy setzt einen healthcheck beim anderen Service voraus. completed wartet, bis ein One-Shot-Service fertig ist. Das passt für Datenbankmigrationen oder Downloads, die vorher laufen müssen. Zyklen sind ein Fehler.

Ein Service mit "oneshot": true läuft einmal durch. Er lässt sich nicht freigeben und zählt nicht zur CPU- und Speichersumme der App.

Internetzugang

Standardmäßig ("egress": "none") hat ein Service keinen Weg ins Internet oder ins lokale Netz. Er erreicht nur die anderen Services der App.

Mit "egress": "public" geht der Service über den Egress-Proxy der App ins Internet. Der Proxy blockt private, Loopback-, Link-Local- und Cloud-Metadaten-Adressen. Der Runner setzt dafür HTTP_PROXY und HTTPS_PROXY. Programme, die diese Variablen ignorieren, können nichts herunterladen. Die Rezeptprüfung warnt bei jedem Service mit öffentlichem Egress.

Ressourcen

Vor dem Deployment addiert Setup die dauerhaft laufenden Services und vergleicht die Summe mit den Grenzen deines Tarifs oder Runners. Geht einem Service der Speicher aus, sagt der Runner das und schlägt vor, memoryMb zu erhöhen.

Hinweis. Setup hostet keine Sprachmodelle. Braucht eine App ein Modell, sollte sie Adresse und Schlüssel einer OpenAI-kompatiblen API als Einstellungen nehmen.

Expose

"expose": { "service": "app", "port": 3000, "path": "/login" }

Checks

"checks": {
  "http": { "path": "/health", "expectStatus": [200], "contains": "ok" },
  "startupTimeoutSeconds": 300
}

Ein Lauf besteht, wenn jeder dauerhafte Service läuft, jeder deklarierte Health-Check gesund ist und der HTTP-Check vor Ablauf der Zeit gelingt. Ohne checks.http ruft der Runner expose.path mit der Standardregel für Statuscodes ab. Weiterleitungen folgt er nicht. Eine Weiterleitung auf eine Login-Seite gilt also als bestanden, solange du kein expectStatus setzt. checks.http braucht expose.

Ein bestandener Lauf verifiziert das Rezept. Was das bewirkt, steht unter Maintainer.

Externe Dienste (requires)

Manche Apps brauchen etwas, das nicht in der Sandbox laufen kann: einen E-Mail-Anbieter, eine gehostete Datenbank, ein Zahlungskonto, einen eigenen OAuth-Client. requires nennt diese Dinge, damit sie sichtbar sind, bevor irgendetwas startet.

"requires": [
  {
    "id": "email",
    "kind": "api-credentials",
    "provider": "resend",
    "capability": "email-sending",
    "title": "Resend for email",
    "reason": "The app sends sign-in links and notifications by email.",
    "inputs": ["RESEND_API_KEY"],
    "docsUrl": "https://resend.com/docs"
  }
]

Der Input selbst ist ein ganz normaler Input, den ein Service über einen Verweis nutzt:

"inputs": [
  {
    "key": "RESEND_API_KEY",
    "label": "Resend API key",
    "description": "Filled when you connect Resend, or enter it yourself.",
    "type": "secret"
  }
]

Beim Deployment listet das Dashboard jede Anforderung unter Externe Dienste auf und bietet Für mich anlegen, Eigene Werte verwenden, Von Hand einrichten und bei optionalen Anforderungen Ohne diesen Dienst starten an. Mit Für mich anlegen legt Setup in einem verbundenen Konto Ressourcen nur für diese eine App an und entfernt sie wieder, wenn du die App entfernst. Der Code dafür stammt aus Setups eigener, geprüfter Registry, nie aus dem analysierten Projekt. Welche Anbieter unterstützt werden, steht unter Integrationen und verbundene Konten.

resources und outputs zählen nur, wenn Setup etwas anlegt. Die Namen der Outputs folgen dem Modul des Anbieters, mit Bindestrichen. Inputs, die nicht in outputs stehen, ordnet Setup über bekannte Namen zu, etwa RESEND_API_KEY.

{
  "id": "database",
  "kind": "managed-service",
  "provider": "cloudflare",
  "capability": "database",
  "title": "Cloudflare D1 database",
  "reason": "The app keeps its data in a D1 database.",
  "inputs": ["D1_DATABASE_ID", "CLOUDFLARE_API_TOKEN"],
  "resources": [{ "type": "d1-database", "name": "db" }],
  "outputs": {
    "D1_DATABASE_ID": "db.database-id",
    "CLOUDFLARE_API_TOKEN": "api-token"
  }
}

Limits

Dein Tarif oder Runner kann für eine ganze App niedrigere Summen setzen.

Fehler und Warnungen

Setup prüft jedes Rezept zweimal: gegen das Schema und dann gegen Regeln, die das Schema nicht ausdrücken kann. Fehler verhindern das Deployment. Warnungen werden angezeigt und blockieren nichts.

Fehler sind unter anderem doppelte Input-Schlüssel, ein select ohne options, unbekannte Verweise, ein Service, der von sich selbst abhängt, eine healthy-Abhängigkeit auf einen Service ohne Health-Check, Abhängigkeitszyklen, ein Build aus dem Quellcode ohne source.git, doppelte Ports oder Volume-Pfade, hostPort ohne publish, ein veröffentlichter HTTP-Port, ein expose, das auf einen fehlenden Service oder einen nicht deklarierten Port zeigt, und checks.http ohne expose.

Warnungen gibt es für nicht gepinnte Image-Tags, veröffentlichte Ports, öffentlichen Egress und jede Anforderung, die nicht optional ist.

Was ein Rezept nicht ausdrücken kann

Das Format hat kein Feld für:

• Ordner auf dem Runner-Host oder Bind-Mounts,
• privileged oder Linux-Capabilities,
• Geräte, abgesehen vom gpu-Flag,
• Host-Netzwerk oder die PID- und IPC-Namespaces des Hosts,
• Sysctls, Kernel-Tuning oder Security-Optionen,
• den Docker-Socket.

Unbekannte Schlüssel verwirft Setup beim Einlesen. Schreibst du "privileged": true in einen Service, gibt es keinen Fehler, es passiert schlicht nichts. Container-Pfade müssen absolut sein, Build-Pfade relativ, und keiner darf .. enthalten.

Der Grund: Setup führt Software aus, die Fremde geschrieben haben, oft auf einem Rechner, den sich mehrere Apps teilen. Jede dieser Optionen würde einem Container einen Weg zum Host oder zu seinen Nachbarn öffnen. Ein Rezept, das sie nicht ausdrücken kann, lässt sich auch nicht dazu überreden. Runner legen ihre eigene Härtung obendrauf: entzogene Capabilities, ein privates Netz pro App, Grenzen für CPU, Speicher und Prozesse. Die einzige Ausnahme zum Einschalten ist publish für rohe Ports, und auch nur auf Runnern, deren Betreiber es erlaubt. Das ganze Modell steht unter Sicherheit.