sevalla-hosting/skills

Bereitstellen von Next.js auf Sevalla

Sevalla ist eine PaaS (von Kinsta) mit zwei Hosting-Produkten für Next.js:

• Application Hosting führt einen echten Node.js-Server aus. Erforderlich für SSR, Route-Handler (API-Routen), Proxy (früher Middleware), ISR (revalidate), Server-Aktionen oder Websockets.
• Static Site Hosting bedient die Ausgabe eines statischen Exports (output: 'export'). Kein serverseitiger Code. Limit von 100 statischen Seiten pro Unternehmen.

Treffen Sie diese Entscheidung zuerst richtig. Sie bestimmt alles Weitere.

Schritt 0: Entscheiden, welches Hosting-Produkt verwendet werden soll

Überprüfen Sie das Repository, bevor Sie etwas anderes tun:

1. Lesen Sie next.config.js / next.config.ts / next.config.mjs auf output: 'export' oder output: 'standalone'.
2. Durchsuchen Sie die Codebasis nach: app/api/, pages/api/, proxy.ts oder proxy.js (Next.js 16), middleware.ts oder middleware.js (Next.js 15 und früher), "use server", getServerSideProps, revalidate (ISR), NextResponse oder einem Datenbank- oder Authentifizierungs-Client, der serverseitig verwendet wird.
3. Entscheiden Sie:
   • Eines der oben genannten vorhanden: Application Hosting (Server erforderlich). Gehen Sie zu Schritt 1.
   • Keines vorhanden, rein statischer Inhalt, Marketing oder Blog: Static Site Hosting ist einfacher und günstiger. Lesen Sie references/static-hosting.md.
   • Unsicher, oder der Benutzer wünscht später dynamische Funktionen: Standardmäßig Application Hosting. Es kann alles, was Static Hosting kann.

Wenn es wirklich mehrdeutig ist, stellen Sie dem Benutzer eine Frage: „Benötigt diese App einen Live-Server (API-Routen, ISR, Authentifizierung, Datenbankaufrufe) oder ist sie vollständig statisch?“ Raten Sie nicht still, denn die falsche Wahl bedeutet, die gesamte Bereitstellung zu wiederholen.

Überprüfen Sie auch das Repository auf einen Datenbank-Client (Prisma, Drizzle, pg, mysql2, Mongoose, redis, ioredis) und auf Dateiuploads. Wenn Sie einen finden, lesen Sie references/data-services.md vor Schritt 3.

Schritt 1: Build-Strategie wählen (Application Hosting)

Sevalla baut Git-basierte Anwendungen mit einer von vier Strategien:

• Nixpacks, die Standardeinstellung. Keine Konfiguration für eine Standard-Next.js-App. Verwenden Sie es, es sei denn, es gibt einen Grund dagegen.
• Railpack, der Nachfolger von Nixpacks. Ebenfalls keine Konfiguration. Eine gute Wahl für eine neue App. Legen Sie es mit dem API-Feld build_type: "railpack" fest.
• Dockerfile, wenn der Benutzer ein kleines, reproduzierbares Image möchte, ein Monorepo hat, mit dem die automatisch erkannten Builder Probleme haben, oder nach Docker fragt.
• Buildpacks (pack). Selten für Next.js erforderlich.

Lesen Sie references/app-hosting.md, bevor Sie Konfigurationen schreiben. Es enthält die genauen package.json-Skripte, das empfohlene Dockerfile, nixpacks.toml-Überschreibungen und die Monorepo-Build-Pfad-Einstellung. Erstellen Sie kein Dockerfile oder nixpacks.toml aus allgemeinem Next.js-Wissen von Hand. Sevalla hat spezifische Einschränkungen (unten), die in generischen Anleitungen nicht erwähnt werden.

Schritt 2: Repository vorbereiten (Sevalla-Einschränkungen)

Diese stolpern fast jede erste Bereitstellung. Überprüfen Sie alle vor dem Bereitstellen:

1. Port von $PORT lesen und an 0.0.0.0 binden. Der Standard-Webprozess-Port ist 8080, und Sevalla übergibt ihn in PORT. Nur die Ports 80 und 443 sind für das Internet geöffnet, und Sevalla leitet sie an $PORT weiter. Bei Nixpacks oder Railpack muss das Startskript next start -p ${PORT:-8080} -H 0.0.0.0 lauten. Ein einfaches next start hört auf Port 3000.
2. NEXT_PUBLIC_*-Variablen werden zur Build-Zeit inline eingefügt. Erstellen Sie sie als Build-Zeit-Variablen (is_buildtime: true) bevor der Build läuft. Eine später hinzugefügte Variable benötigt eine neue Bereitstellung, keinen Neustart.
3. Das Dateisystem ist flüchtig. Alles, was die App zur Laufzeit auf die Festplatte schreibt (Uploads, generierte Dateien, Caches auf der Festplatte), geht bei jeder erneuten Bereitstellung oder jedem Neustart verloren. Verwenden Sie Objektspeicher oder eine persistente Festplatte, wenn die App wirklich lokale Festplatten-Schreibvorgänge benötigt (z. B. SQLite oder ein selbst gehostetes CMS). Siehe references/data-services.md.
4. output: 'standalone' nur mit dem Dockerfile. next start verwendet das Standalone-Bundle nicht, und Next.js warnt: "next start" does not work with "output: standalone" configuration. Lassen Sie bei Nixpacks oder Railpack output daher nicht gesetzt. Verwenden Sie beim Dockerfile output: 'standalone'.
5. node_modules oder .next nicht committen. Ein committeter node_modules-Ordner ist eine dokumentierte Ursache für fehlgeschlagene Builds auf Sevalla.
6. Node.js-Version festlegen. Nixpacks verwendet standardmäßig Node 18, und Next.js 16 benötigt Node 20.9 oder höher. Setzen Sie "engines": { "node": "22.x" } in der package.json oder die Build-Zeit-Variable NIXPACKS_NODE_VERSION=22.
7. Monorepos: Setzen Sie den Build-Pfad (API-Feld build_path) auf den Ordner der Next.js-App, z. B. apps/web. Setzen Sie beim Dockerfile auch docker_context und dockerfile_path.
8. package.json-Name: Verwenden Sie nicht "node" oder "js" als Paketnamen. Es ist dokumentiert, dass dies Sevalla-Builds zerstört.
9. Doppelte Anführungszeichen in Variablenwerten müssen als \" maskiert werden. Nicht maskierte Anführungszeichen werden entfernt oder lassen den Rollout fehlschlagen.
10. Geheimnisse (Datenbank-URLs, API-Schlüssel) kommen in Sevalla-Umgebungsvariablen. Committen Sie niemals eine .env-Datei mit echten Geheimnissen.

Schritt 3: Bereitstellen

Verwenden Sie die erste verfügbare Option in dieser Reihenfolge:

1. Der Sevalla MCP-Server (https://mcp.sevalla.com/mcp). Er hat zwei Werkzeuge: search findet API-Endpunkte in der Spezifikation, und execute führt JavaScript aus, das sevalla.request({ method, path, body }) aufruft. Verwenden Sie die API-Pfade in der Tabelle unten.
2. Die sevalla CLI, mit --json bei jedem Befehl, damit Sie die IDs lesen können. Installieren Sie mit npm install -g @sevalla/cli (Node 22+) oder brew install sevalla-hosting/tap/sevalla. Melden Sie sich mit sevalla login an (Geräteautorisierung im Browser) oder setzen Sie SEVALLA_API_TOKEN.
3. Die REST API unter https://api.sevalla.com/v3 mit einem Bearer-API-Schlüssel.

Wenn keine verfügbar ist, sagen Sie dem Benutzer, wie er den MCP-Server hinzufügt (siehe Quick-Starts für Coding-Agenten unter https://docs.sevalla.com/quick-starts/coding-agents/overview), oder geben Sie ihm die Dashboard-Schritte in references/dashboard.md. Nur der erste Login benötigt den Benutzer.

Application Hosting

#	Aktion	API (MCP execute oder REST)	CLI
1	Standort auswählen	GET /resources/clusters	sevalla resources clusters --json
2	App erstellen	POST /applications mit display_name, cluster_id, source (privateGit für ein verbundenes GitHub-, GitLab- oder Bitbucket-Repo, publicGit für eine öffentliche URL), git_type, repo_url, default_branch	sevalla apps create --name <name> --cluster <cluster-id> --source privateGit --git-type github --repository https://github.com/<owner>/<repo> --branch <branch> --json
3	Build-Strategie und Build-Pfad setzen, falls nicht Standard	PATCH /applications/{id} mit build_type (nixpacks, railpack, dockerfile, pack) und build_path	sevalla apps update <app-id> --build-type railpack --json. Die CLI hat kein Build-Pfad-Flag: sevalla apps update <app-id> --data '{"build_path":"apps/web"}' --json
4	Umgebungsvariablen hinzufügen	POST /applications/{id}/env-vars mit key und value. is_runtime und is_buildtime sind standardmäßig beide true, was für NEXT_PUBLIC_* richtig ist.	sevalla apps env-vars create <app-id> --key <KEY> --value "<value>" (zur Build-Zeit und zur Laufzeit verfügbar)
5	Datenbank verbinden, falls vorhanden	Siehe references/data-services.md
6	Bereitstellen	POST /applications/{id}/deployments. Das Erstellen einer App startet keine Bereitstellung.	sevalla apps deployments trigger <app-id> --branch <branch> --json

Wenn Schritt 2 mit HTTP 500 für ein privateGit-Repo fehlschlägt, ist die wahrscheinlichste Ursache, dass Sevallas GitHub-App das Repository nicht sehen kann. Die API sagt dies nicht. Überprüfen Sie mit sevalla git providers --json: Die settings_url öffnet die GitHub-App-Installation. Der Benutzer (oder ein Eigentümer der GitHub-Organisation) muss der App Zugriff auf das Repository gewähren. Ein Repository in einer Organisation, deren Eigentümer der Benutzer nicht ist, benötigt einen Eigentümer, der es hinzufügt. Versuchen Sie dann Schritt 2 erneut.

Eine neue App hat die automatische Bereitstellung deaktiviert. Wenn der Benutzer bei jedem Push eine Bereitstellung wünscht, setzen Sie auto_deploy: true mit PATCH /applications/{id} (funktioniert nur für privateGit).

Für Static Site Hosting folgen Sie stattdessen references/static-hosting.md. Das Erstellen einer statischen Seite startet automatisch ihre erste Bereitstellung.

Schritt 4: Überprüfen

Eine gestartete Bereitstellung bedeutet nicht, dass sie funktioniert. Führen Sie alle folgenden Schritte aus, bevor Sie dem Benutzer mitteilen, dass sie abgeschlossen ist:

1. Auf den Build warten. Fragen Sie GET /applications/{id}/deployments/{deployment_id} ab (CLI: sevalla apps deployments get <deployment-id> --app-id <app-id> --json) alle 15 bis 30 Sekunden, bis der status success oder failed ist. Andere Werte sind waiting, inProgress, cancelled und skipped.
2. Wenn er fehlgeschlagen ist, lesen Sie das Build-Protokoll. GET /applications/{id}/deployments/{deployment_id}/logs (CLI: sevalla apps deployments logs ...). Gleichen Sie den Fehler mit der Fehlerbehebungstabelle in references/app-hosting.md ab, beheben Sie die Ursache und stellen Sie erneut bereit. Raten Sie nicht zweimal, ohne das Protokoll zu lesen. Bewerten Sie den Erfolg anhand des Bereitstellungs-status, nicht anhand der Protokollschwere: Normale Build-Ausgabe, die nach stderr geschrieben wird, erscheint mit "severity": "error" in einem erfolgreichen Build.
3. Finden Sie die Live-URL. GET /applications/{id}/domains (CLI: sevalla apps domains list --app-id <app-id> --json). Jede App erhält nach ihrer ersten erfolgreichen Bereitstellung eine kostenlose *.sevalla.app-Domain.
4. Rufen Sie die URL auf. Erwarten Sie HTTP 200 auf / und auf einem Route-Handler, falls die App einen hat. Ein 502 oder ein Timeout bedeutet normalerweise, dass der Server nicht auf $PORT und 0.0.0.0 lauscht.
5. Wenn die App mit einem Fehler antwortet, lesen Sie das Laufzeitprotokoll. GET /applications/{id}/runtime-logs (CLI: sevalla apps logs runtime <app-id>).

Teilen Sie dem Benutzer dann die Live-URL mit, was Sie konfiguriert haben und was er selbst tun muss (z. B. DNS-Einträge für eine benutzerdefinierte Domain hinzufügen).

Schritt 5: Optionale nächste Schritte

• Benutzerdefinierte Domain: sevalla apps domains add <app-id> --name example.com. Der Benutzer muss die DNS-Einträge hinzufügen, die Sevalla zurückgibt. SSL ist enthalten.
• Skalierung: sevalla apps processes update <process-id> --app-id <app-id> --instances <n>. Verwenden Sie bei mehr als einer Instanz keine persistente Festplatte für gemeinsamen Zustand. Verwenden Sie Objektspeicher oder eine Datenbank.
• Rollback: sevalla apps deployments rollback <app-id> --deployment-id <id>.

Referenzdateien

• references/app-hosting.md: package.json-Skripte, Nixpacks- und Railpack-Hinweise, das empfohlene Dockerfile, Monorepo-Setup, Fehlerbehebungstabelle.
• references/static-hosting.md: Statischer Export-Setup und Bereitstellung für Static Site Hosting.
• references/data-services.md: Datenbanken, Objektspeicher und persistente Festplatten und wie ihre Verbindungsdetails die App erreichen.
• references/dashboard.md: Die gleichen Schritte im Sevalla-Dashboard, für einen Menschen.