Platform

Platform covers where your Kumiko app runs, including hosting, deployment, and operations. Self-hosting is the only option today. The hosted kumiko.rocks/cloud variant is in preparation and will get its own section when it becomes 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. Schema-apply 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/ + kumiko/migrations/. A pre-deploy step bun /app/kumiko.js schema apply runs against the DB; the boot gate verifies the schema; the container starts.

Reference: the deploy/Dockerfile that kumiko new app scaffolds, from the framework template Dockerfile.template.

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

K3s

Status: ✅ Stable · Guide

When: Multi-replica, Postgres HA, a dedicated worker lane for background jobs, infrastructure-as-code, and compliance requirements such as backups, secret rotation, and RBAC.

How it runs: An infrastructure-as-code layer provisions a Postgres cluster, Redis, ingress, certificates, app and worker deployments, dedicated database roles, resource quotas, and backup schedules. Use the K3s deployment guide for the environment-specific procedure.

Reference setup: the publicstatus showcase uses this topology. The cluster automation is an internal deployment implementation, not a public dependency of Kumiko.

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

Pre-deploy schema apply

Whichever mode, before the server starts, kumiko schema 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 schema apply

The bundled kumiko.js applies pending SQL under kumiko/migrations/ 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 schema apply deliberately.

Server bundle vs. native externals

bun run build bundles everything into one ~1 MB JS file: framework, bundled features, app source, schemas. A short list of packages stays external because Bun cannot bundle them (native bindings, worker loaders, dynamic requires) or because the app loads them at runtime:

@node-rs/argon2, sharp, bullmq, ioredis, postgres, temporal-polyfill,
pino, pino-pretty, meilisearch

Add app-specific runtime packages under kumiko.extraRuntimeExternals in the app’s package.json. temporal-polyfill stays on the list only as the runtime fallback behind @cosmicdrift/kumiko-types/temporal. App code imports Temporal from that module, never from temporal-polyfill directly (see Upgrade Kumiko).

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.rocks/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	No public operational page yet. Treat image updates as an explicit deployment concern.

Cloud (coming)

Status: ⬜ Planned, kumiko.rocks/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

Deployment-specific runbooks

The public pages above describe the supported deployment shapes and the framework boundary. Provider credentials, cluster names, infrastructure-stack details, and incident runbooks belong to the operator’s private deployment repository; they are intentionally not linked from the public docs.