skills/kora-self-host/references/update-and-license.md

# Updates, Forward Recovery, And License Operations

## Online Updates

```sh
./koractl update latest
./koractl update 0.2.0
```

Online update downloads a release bundle from the configured release base
URL, verifies the checksum, applies bundle-owned files, and restarts Kora.

The self-managed 0.11-to-0.12 boundary is a one-time clean-break exception.
Only the latest 0.11 database watermark can update directly; older installs
must update to latest 0.11 first. The 0.12 updater backs up both databases and
workspace state, terminates shipped workflows, undeploys every environment,
deprovisions managed event streams, deletes retired Core timer schedules, and
recompiles stored process YAML.
Rejected YAML is preserved under `recovery/0.12/processes/`; environments stay
undeployed until the operator reviews source and explicitly deploys fresh
releases.

If a failed 0.12 release candidate already recorded
`schema-migration-started`, its old `koractl` cannot parse the recovery flag.
Use the corrected target's public bootstrap takeover explicitly:

```sh
curl -fsSL https://kora.raw-labs.com/install.sh | bash -s -- \
  --version <corrected-0.12-tag> \
  --dir <existing-install> \
  --existing-action update \
  --apply-0.12-migration
```

If the corrected updater is already installed, finish with
`./koractl start --apply-0.12-migration` instead. Do not restore an old bundle
after Temporal schema migration has begun.

Both recovery forms stop the Platform API, chat service, and Core and Platform
workers before taking any missing database or workspace backup. A failed
forward-only recovery keeps those writable services stopped.

If the Platform migration ledger already advanced past 120, recovery continues
only when `.rendered/platform-0.12-cutover-state` records
`data-cutover-complete`. `koractl` does not treat later ordinary migrations as
proof that environment retirement and Process recompilation already ran.

The first bundled Temporal 1.29 to 1.30.6 update may require two
invocations on an installation that still has the released legacy updater. The
first invocation installs the forward-only updater and exits before Temporal
schema work. The released updater may already have quiesced Kora services, so
run both invocations in the same maintenance window and rerun the update
promptly to continue.

Bootstrap `reinstall` over an existing installation retains its databases and
therefore delegates to this guarded update path. The Temporal schema job also
requires a version-specific authorization projected by the matching `koractl`;
raw Compose startup is not a supported schema-upgrade path.

The single `.rendered/temporal-schema-update-state` file records
`updater-installed <version>` before updater promotion and
`schema-migration-started <version>` once only the target version may continue.
Ordinary startup cannot bypass the first state, and the second update bundle
must declare that same target Temporal version; the second state recovers with
`./koractl start`. The state file is cleared after the target stack and
schedules recover.
Before replacing bundle files, `koractl` checks Temporal for every running
workflow type shipped by the Core and Platform workers. The default update
aborts if one exists. Wait for those Temporal workflow executions to finish,
or explicitly choose a clean-break update:

```sh
./koractl update 0.2.0 --terminate-running
```

During either update path, `koractl` stops the running Core worker, Platform
worker, Platform API, and Platform chat service, and pauses Kora timer schedules
before the final workflow-type check. The flag additionally terminates all
running Kora workflow types through Temporal. The update does not normally
undeploy environments or delete schedules; those start sources return with the
updated stack. The documented 0.11-to-0.12 bridge above is the exception.
Ordinary `start`, `stop`, and `restart` commands never terminate Temporal
workflow executions.
The supported in-flight policy for the Temporal server cutover is a clean drain
or explicit `--terminate-running`; representative replay validation is not a
blanket compatibility claim for every workflow history.

For offline or controlled Enterprise updates, provide the bundle directly and
pass the checksum file when available:

```sh
./koractl update --bundle ./kora-platform-deploy-0.2.0.tar.gz --checksum ./kora-platform-deploy-0.2.0.tar.gz.sha256
```

The update command preserves operator-owned files, installs the target updater
before schema work, updates `KORA_IMAGE_TAG`, and starts the target stack.

## Forward Recovery

If startup fails before schema work begins, correct the target problem and rerun
`./koractl update`. If `.rendered/temporal-schema-update-state` contains
`schema-migration-started`, Temporal, API, and worker services remain stopped;
correct the target problem and run `./koractl start`. Schema and namespace setup
are idempotent.

`.rendered/temporal-schema-version-floor` prevents an older bundle from being
installed after a successful schema cutover. Do not delete the floor or run an
older Temporal image against the migrated database.

Workflow executions terminated by `--terminate-running` do not return. Start a
new workflow rather than resetting one across the release boundary.

The bundled 1.30.6 pin does not set or imply the server version of Temporal
Cloud or another managed provider. Managed promotion requires authoritative
provider-equivalence evidence plus an isolated greater-than-4 MiB Workflow Task
canary, representative replay, and an unrelated-workflow health proof.
## License Operations

```sh
./koractl license status
./koractl license activate --install-session kora_ins_...
./koractl license install-file --license ./license.json --keys ./license-public-keys.json
```

`license activate` claims an online install session and writes
`license/license.json`, `license/license-public-keys.json`,
and `license/license-deployment-token`.
`license install-file` is the offline path for out-of-band license material.

## Deployment Token Hygiene

`license/license-deployment-token` is a bearer secret used by Platform API
check-ins and by the Platform worker only to inject online account context
into granted extension handlers. Keep it owner-readable only. Do not log it,
commit it, or send it to support.

## Offline Image Handling

Air-gapped image delivery is an Enterprise packaging concern, not a public
installer prompt or an update flag. The customer-facing path is a prepared
offline package with its own instructions.