Use and administer Runku

This documentation explains how to build applications on Runku and operate Runku Self-Hosted. It is organized by responsibility so application code, CLI workflows, and server administration do not blur together.

Choose your path

You want to…	Start here	You will work with
build an application backend	Application tutorial	schemas, Query/Mutation/Action, data, auth, client
look up an exact Function parameter/type/limit	Function API reference	@runku/server declarations and handler context
call Runku from TypeScript	TypeScript client	@runku/client, typed calls, Realtime, file grants
use React or Next.js	React and Next.js integration	hooks, SSR hydration, server calls, generated references
call Runku without an SDK	Public HTTP API	canonical HTTP/JSON, credentials, retries
use the command line	CLI guide	local dev, login/link, publish, promote, rollback
install Self-Hosted	Deployment guide	compact Docker package, TLS, state, readiness
operate an installation	Operator handbook	health, logs, backup, upgrades, incidents
configure the Runku Storage backend	Storage configuration	filesystem/external object-store bytes, quota, capacity, recovery

Application development

Follow this route when writing the backend and the application that consumes it:

1. Application tutorial — complete first application.
2. Schema and data types — every validator, table/index rule, naming constraint, size/depth limit, and rollout concern.
3. Query, Mutation, and Action — choose the correct semantic operation, define authentication/visibility/capabilities, handle retries/effects/scheduling.
4. Function API reference — exact declaration fields, handler parameters, context methods, capability matrix, and runtime limits.
5. Documents and indexes — IDs, reads/writes, revisions, OCC, index ordering, scan constraints, pagination limits, and Realtime dependencies.
6. Data and Realtime — broader transaction, outbox, subscription, resync, and administrative-data contract.
7. Application identity — Application Clients, functional identity, public/secret/development credentials, JWT/OIDC, browser/server separation, and rotation.
8. Environment variables and secrets — declare and read exact configuration capabilities safely.
9. Application Files — Action permissions, grant parameters, streaming, direct bytes, lifecycle, limits, and recovery consequences.
10. TypeScript client or HTTP without an SDK — consume the application API.

Use Application development workflow for build, Dev Revision, Release, Channel, compatibility, testing, and delivery as one task flow.

Storage products

Runku exposes two distinct application-facing storage capabilities:

Capability	Application interface	Administration	Best for
Application Files	Action ctx.storage + short-lived HTTP grants	Self-Hosted byte quota/backend	user attachments and authorized transfers
Runku Object Storage	Runku Product route with S3-compatible protocol	buckets, policies, CORS, quotas, Product access keys	application objects and compatible tooling

Read Application Files or Runku Object Storage for usage. Operators should separately read Storage configuration and limits, because the physical filesystem or external object-store credentials, capacity, backup, and migration are installation concerns.

CLI

The CLI guide covers:

• installation and supported platforms;
• init, dev, build, status, doctor, and local logs;
• Self-Hosted login and Environment link;
• remote publish, Release freeze, Channel promotion, and rollback;
• local versus remote authority, CAS conflicts, exit-code behavior, and security.

Use the CLI reference when you need exact syntax and flags. The CLI does not define Function parameters and is not the runku-server administration/configuration interface.

Self-Hosted installation

Read in this order:

1. Self-hosting overview — current supported distribution and fit.
2. Compact deployment guide — plan, install, expose TLS, initialize ownership, publish, verify, and remove.
3. Docker package — exact package commands and profiles.
4. Server configuration — runku-server commands, listeners, identity, Product database, browser auth, logs, and validation.
5. Storage configuration — filesystem or external object-store parameters, capacity, credentials, canaries, backup, restore, and backend changes.
6. Function data PostgreSQL — optional Environment-scoped document/index/outbox/schedule database and its recovery boundary.
7. Production readiness — explicit go/no-go criteria.

The current supported package is a compact non-root runku-server plus Docker Compose for one initialized Safe V8 Product Environment. Repository assets for separated general-purpose roles, Kubernetes, and VM-isolated shared Full Node are not a supported Helm/cluster distribution.

Operate Self-Hosted

Use these guides after installation:

1. Operator handbook — routine checks, safe changes, rollout, incident triage, restart, restore decisions, and evidence.
2. Administration — Environment lifecycle, credentials, retention, capacity, maintenance, and incidents.
3. Observability — signal catalog, dashboards, alerts, correlation, privacy, and OTLP behavior.
4. Operational logs — standalone/HA storage, query/follow, archive frontier, retention, recovery, sizing, and upgrades.
5. Backup and recovery — state inventory, compact commands, restore verification, external dependencies, and disaster recovery.
6. Upgrades and rollback — server/database/package change procedure.
7. Capacity planning — workload model, resource signals, saturation tests, and limits.
8. Troubleshooting — symptom-first diagnosis.

Application Release rollback and Self-Hosted server rollback are different operations. A Channel move does not restore data, change the binary, or reverse an external effect.

Identity and security

• Identity map distinguishes Application Client, functional principal, Platform operator, file grant, Product storage key, and physical provider credential.
• Application identity covers runtime callers.
• Platform operator identity covers owners, invitations, OIDC, sessions, grants, and recovery.
• Security model covers trust boundaries, threats, controls, secrets, and residual risk.
• Hardening checklist is the deployment acceptance checklist.

Credentials cannot exchange roles. In particular, an Application Key cannot call the Management API, an operator token cannot replace a Function bearer/file grant, and a Runku Storage Product key is not the physical external-backend credential held by runku-server.

Administration APIs

Use the Management API reference only when building an operator UI or controller. It covers Platform sessions/capabilities, exact Project/Environment scope, CAS, idempotency, one-time secret responses, lifecycle, Releases/Channels, configuration, credentials, storage, data administration, schedules/Cron, logs, and errors.

Application clients use the Public HTTP API. Never expose the Management origin/token as an application backend API.

Product model

The durable vocabulary is:

• Environment = persistent state;
• Release = immutable code;
• Channel = traffic policy;
• Workspace = mutable pointer to immutable development revisions.

Read Platform model, Environment lifecycle, Serving policy, and Releases and Workspaces when operating delivery/routing. Every request, subscription, nested call, Cron activation, and scheduled invocation pins exact code for its defined lifetime; there is no implicit latest.

Support status vocabulary

Documentation uses these states precisely:

State	Meaning
Implemented	available in the current product path described
Conformance	a bounded contract/test exists; this alone is not installation support
Production requirement	acceptance criterion that must be met before production use
Pre-release limitation	capability or guarantee deliberately not promised by the current line

Start with Capability and support status before relying on optional runtimes, distributed topology, HTTPS egress, storage backends, or backup guarantees.

Validate in Runku SaaS

SaaS validation can shorten application contract validation: schemas, Functions, clients, identity behavior, canonical calls, Release targeting, and supported storage flows can be compared there when enabled.

SaaS validation does not prove Self-Hosted TLS, proxy behavior, physical Runku Storage backend policy, PostgreSQL, capacity, backup/restore, upgrade, or incident readiness. Repeat those acceptance tests on the actual Self-Hosted installation.