Platform

Platform describes where your Kumiko app runs — hosting, deployment, operations. Self-hosting is the only path today; the hosted kumiko.so/cloud variant is in preparation and will get its own section here when it goes public.

Self-hosting paths

Three modes, same server bundle. bun run build produces dist-server/server.js — the difference between modes is orchestration + DB setup, not the app code.

Solo

Status: ✅ Stable · Guide

When: Single-tenant apps, internal tools for one company, self-hosters with a single server. No multi-replica, no Postgres HA, no Pulumi.

How it runs: One Bun process on a VM, Postgres + Redis as Docker containers next to it (or as a systemd service). Caddy or nginx in front for TLS. Migrate-step at boot; the server boot blocks on schema drift.

Recommended for: Tools for 1–50 users, no compliance pressure, operator is the developer.

Docker

Status: ✅ Stable · Guide

When: Reproducible image builds, deployment to Coolify / Dokku / Hetzner Cloud / DigitalOcean App Platform. You don’t want to install Bun and git pull per server.

How it runs: A multi-stage Dockerfile builds the server bundle; the runtime image (~270 MB, oven/bun-alpine base) only carries dist/ + dist-server/ + drizzle/. A pre-deploy step bun /app/kumiko.js migrate apply runs against the DB; the boot gate verifies the schema; the container starts.

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

Recommended for: Production deployments with clear CI/CD, one or two tenants, moderate load.

k3s

Status: ✅ Stable · Guide

When: Multi-replica, Postgres HA with CNPG, dedicated worker lane for background jobs, Pulumi for infrastructure-as-code. Compliance requirements (backups, secret rotation, RBAC).

How it runs: Pulumi provisions: Postgres cluster (CNPG HA), Redis, ingress, cert-manager, app deployment with replicas, worker deployment with its own replica count, per-app Postgres role with ResourceQuota. Operator pods react to custom CRDs for app lifecycle.

Reference setup: infra/pulumi/operators in the publicstatus showcase.

Recommended for: Production with multi-tenant workload, compliance pressure, dedicated ops team.

Pre-deploy migrate step

Whichever mode — before the server starts, kumiko migrate apply runs. This is the only place the DB schema changes.

# In the pre-deploy container (before the app container comes up):
docker run --rm --network <stack>_stack \
  -e DATABASE_URL="postgresql://user:pw@db:5432/dbname" \
  <image> bun /app/kumiko.js migrate apply

The bundled kumiko.js calls drizzle-kit and (if present) the app-specific migration-hooks.js for rebuildProjection markers.

Boot gate: if the server sees pending migrations or missing tables at boot → SchemaDriftError, container exits. No auto-heal, no silent skip — the operator must call migrate apply deliberately.

Server bundle vs. native externals

bun run build bundles everything into one ~1 MB JS file: framework, bundled features, app source, Drizzle schemas. Seven native packages remain as externals (they have native bindings Bun cannot bundle):

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

Versions are pinned by packages/framework/package.json. In the runtime container, bun install --production against the generated dist-server/package.json populates node_modules/ (~30 MB). Total image size: ~270 MB.

Operational topics

Detail pages are coming with the kumiko.so/cloud variant. Until then, stub references:

Topic	Status	Note
Backups	⬜ Detail page planned	Recipe encrypted-tenant-config shows the encryption pattern. The Pulumi stack provisions Postgres backups via CNPG.
Monitoring	⬜ Detail page planned	/api/health reports ready/live; every boot logs an instance ID.
Secret rotation	⬜ Detail page planned	The secrets feature has a built-in rotateJob. JWT-secret rotation via multi-key lookup is planned.
Migrations on deploy	✅ Stable	Pre-deploy step (above). The boot gate enforces schema consistency.
Multi-region	⬜ Planned	Tenant-aware routing + read replicas — architectural decision in a plan doc, not yet in the repo.
Auto-update	⬜ Planned	Concept exists as an internal plan snapshot — see docs/plans/architecture/auto-update.md in the framework repo.

Cloud (coming)

Status: ⬜ Planned — kumiko.so/cloud as the hosted SaaS variant.

It will eliminate most of the operational topics above — backups, monitoring, secret rotation, migrations all run on our side. You bring code (git push) + domain; we bring the rest. Pricing and sign-up will follow when the platform is public.

Self-hosting stays first-class — no lock-in. The cloud variant is a convenience layer, not a different code path.

See also

Where do I find…	Here
What the app actually does (pipeline, multi-tenant, …)	Concepts
Pre-built features (auth, audit, jobs, …)	Bundled features
First local steps	Quickstart
Production build conventions (server bundle, externals)	Samples overview
Pattern reference (r.entity, r.hook, …)	Reference / Patterns