Platform

Platform beschreibt, wo deine Kumiko-App läuft — Hosting, Deployment, Operationelles. Heute ist Self-Hosting der einzige Pfad; die gehostete kumiko.so/cloud-Variante ist in Vorbereitung und bekommt hier eine eigene Sektion sobald sie öffentlich ist.

Self-Hosting-Pfade

Drei Modi auf demselben Server-Bundle. yarn build produziert dist-server/server.js — der Unterschied zwischen den Modi ist Orchestration + DB-Setup, nicht der App-Code.

Solo

Status: ✅ Stable · Anleitung

Wann: Single-Tenant-Apps, internes Tool für eine Firma, Self- Hoster mit einem Server. Du brauchst keine Multi-Replica, kein Postgres-HA, kein Pulumi.

Wie es läuft: Ein Bun-Prozess auf einer VM, Postgres + Redis als Docker-Container daneben (oder als Systemd-Service). Caddy oder Nginx davor für TLS. Migrate-Step beim Boot, Server-Boot blockt bei Schema- Drift.

Empfohlen für: Tools für 1-50 Nutzer, kein Compliance-Druck, Operator ist Entwickler.

Docker

Status: ✅ Stable · Anleitung

Wann: Reproduzierbare Image-Builds, Deployment auf Coolify / Dokku / Hetzner Cloud / DigitalOcean App-Platform. Du willst nicht pro Server bun installieren und git pullen.

Wie es läuft: Multi-Stage Dockerfile baut das Server-Bundle, Runtime- Image (~270 MB, oven/bun-alpine-Base) hat nur dist/ + dist-server/

drizzle/. Pre-Deploy-Step bun /app/kumiko.js migrate apply läuft gegen die DB, Boot-Gate prüft Schema, Container fährt hoch.

Reference: samples/showcases/publicstatus/deploy/Dockerfile + .github/workflows/deploy-publicstatus.yml.

Empfohlen für: Production-Deployments mit klarem CI/CD, ein bis zwei Tenants, mittlere Last.

k3s

Status: ✅ Stable · Anleitung

Wann: Multi-Replica, Postgres-HA mit CNPG, dedicated Worker-Lane für Background-Jobs, Pulumi für Infrastructure-as-Code. Compliance- Anforderungen (Backups, Secret-Rotation, RBAC).

Wie es läuft: Pulumi provisioniert: Postgres-Cluster (CNPG-HA), Redis, Ingress, Cert-Manager, App-Deployment mit Replicas, Worker-Deployment mit eigener Replica-Count, Per-App-Postgres-Role mit ResourceQuota. Operator-Pods reagieren auf benutzerdefinierte CRDs für App-Lifecycle.

Reference-Setup: infra/pulumi/operators in der publicstatus-Showcase.

Empfohlen für: Production mit Multi-Tenant-Workload, Compliance- Druck, eigenes Ops-Team.

Pre-Deploy-Migrate-Step

Egal welcher Modus — vor dem Server-Start läuft kumiko migrate apply. Das ist die einzige Stelle wo DB-Schema geändert wird.

# Im Pre-Deploy-Container (vor dem App-Container hochfährt):
docker run --rm --network <stack>_stack \
  -e DATABASE_URL="postgresql://user:pw@db:5432/dbname" \
  <image> bun /app/kumiko.js migrate apply

Der gebundelte kumiko.js ruft drizzle-kit + (wenn vorhanden) den App-spezifischen migration-hooks.js für rebuildProjection-Marker.

Boot-Gate: Wenn der Server-Boot pending Migrations oder fehlende Tabellen sieht → SchemaDriftError, Container exit. Kein Auto-Heal, kein silent skip — der Operator muss bewusst migrate apply rufen.

Server-Bundle vs. Native-Externals

yarn build bündelt alles in eine ~1 MB JS-Datei: Framework, bundled-features, App-Source, Drizzle-Schemas. Sieben native Pakete bleiben als Externals (sie haben native-Bindings die Bun nicht bündeln kann):

argon2, bullmq, drizzle-kit, drizzle-orm,
ioredis, postgres, temporal-polyfill

Versions-Pinning kommt aus packages/framework/package.json. Im Runtime-Container füllt bun install --production gegen das generierte dist-server/package.json die node_modules/ (~30 MB). Total-Image- Size: ~270 MB.

Operationelle Topics

Detail-Pages folgen wenn die kumiko.so/cloud-Variante steht. Bis dahin Stub-Hinweise:

Topic	Status	Hinweis
Backups	⬜ Detail-Page geplant	Recipe `encrypted-tenant-config` zeigt Encryption-Pattern. Pulumi-Stack provisioniert Postgres-Backups via CNPG.
Monitoring	⬜ Detail-Page geplant	`/api/health` liefert ready/live, jeder Boot loggt instance-id.
Secret-Rotation	⬜ Detail-Page geplant	`secrets`-Feature hat eingebauten `rotateJob`. JWT-Secret-Rotation via Multi-Key-Lookup geplant.
Migrations on Deploy	✅ Stable	Pre-Deploy-Step (siehe oben). Boot-Gate enforced Schema-Konsistenz.
Multi-Region	⬜ Geplant	Tenant-Aware-Routing + Read-Replicas — Architektur-Entscheidung in Plan-Doc, noch nicht im Repo.
Auto-Update	⬜ Geplant	Konzept als interner Plan-Snapshot — siehe `docs/plans/architecture/auto-update.md` im Framework-Repo.

Cloud (kommend)

Status: ⬜ Geplant — kumiko.so/cloud als gehostete SaaS-Variante.

Wird die meisten Operationellen Topics oben eliminieren — Backups, Monitoring, Secret-Rotation, Migrations laufen bei uns. Du bringst Code (Git-Push) + Domain, wir bringen den Rest. Pricing + Sign-up folgen wenn die Plattform öffentlich ist.

Self-Hosting bleibt first-class — kein Lock-in. Die Cloud-Variante ist ein Convenience-Layer, kein anderer Code-Pfad.

Siehe auch

Wo finde ich…	Hier
Was die App eigentlich tut (Pipeline, Multi-Tenant, …)	Framework
Fertige Features (Auth, Audit, Jobs, …)	Bundled-Features
Erste lokale Schritte	Quickstart
Production-Build-Conventions (Server-Bundle, Externals)	Samples-Übersicht
Konzept-Tiefen-Docs (Migrations, Lifecycle, Permissions, …)	Architecture