fix(kura): clarify self-host standalone setup

What changed

• Clarified the Kura self-host standalone example so KURA_NODE_URL is presented as the node’s required peer identity, while KURA_PEERS is only needed for multi-node meshes.
• Reworked the standalone compose sample to start from a trusted single-node, no-server setup, then documented the self-hosted Tuist server auth/registration overlay and multi-node peer TLS additions separately.
• Documented that no-server validation should leave KURA_EXTENSION_* unset, and that auth setups need either an image that includes /etc/kura/extensions/tuist.lua or a mounted hook at KURA_EXTENSION_SCRIPT_PATH.
• Fixed the release Kura image assembly so Dockerfile.release bundles the same Tuist auth hook as the source-build Dockerfile.
• Updated the self-host server compose bundle to use clickhouse/clickhouse-server:26.5-alpine for both ClickHouse and ClickHouse Keeper.
• Updated the local self-hosting docs to mention ClickHouse 26.5 and call out bind-mount ownership expectations for persistent host directories.

Why

The standalone Kura documentation grouped KURA_NODE_URL and KURA_PEERS under a comment saying the mesh configuration was only needed when running more than one node. In practice, Kura requires KURA_NODE_URL even for a single node because it is the node’s own identity and the default seed used when KURA_PEERS is omitted.

That mismatch led to this startup failure when following the single-node interpretation of the sample:

invalid configuration: missing required environment variables: KURA_NODE_URL

The previous sample also enabled the Tuist extension hook in the default standalone block. That is valid when the node is meant to authenticate against a Tuist server, including a self-hosted Tuist server, but it is wrong for the no-server validation path and it assumes the hook exists in the image.

The source-build kura/Dockerfile already copied ops/helm/kura/hooks/tuist.lua into /etc/kura/extensions/tuist.lua, but published Kura runtime images are built with kura/Dockerfile.release, which did not copy that file. That is why the currently published ghcr.io/tuist/kura:latest image lacks the hook even though the source Dockerfile appears correct.

Separately, ClickHouse Keeper users persisting data with host bind mounts reported permission trouble with the older image line. Pinning the newer Alpine image keeps the bundled self-host stack aligned with the version that behaves better for that setup, while the docs now remind operators to prepare writable bind-mount directories.

Approach

The change keeps the Kura runtime behavior as-is and fixes the published guidance instead. The default standalone example is now the smallest trusted single-node setup: KURA_NODE_URL remains required, it uses http://...:7443, and it omits KURA_PEERS, peer TLS, control-plane registration, and extension auth.

The auth section now shows the extra variables to add for a Kura node connected to a self-hosted Tuist server: control-plane credentials, registration, extension settings pointed at the self-hosted server URL, and a hook mount when the image does not bundle /etc/kura/extensions/tuist.lua. The multi-node section separately covers the peer TLS switch to https://.

Dockerfile.release now bundles ops/helm/kura/hooks/tuist.lua at /etc/kura/extensions/tuist.lua, so future published runtime images match the documented extension path.

For the self-host compose bundle, both ClickHouse services now use the same 26.5-alpine tag so Keeper and server stay on a consistent ClickHouse version.

Validation

• Verified clickhouse/clickhouse-server:26.5-alpine exists on Docker Hub for amd64 and arm64.
• Ran docker compose config from a temp copy of server/priv/static/server/self-host with .env.example copied to .env.
• Ran git diff --check / git diff HEAD --check.
• Validated standalone Kura from the self-host assumptions without connecting it to Tuist server: /up, /ready, CAS upload/download, keyvalue write/read, plaintext internal /_internal/status, and persistence across a container restart with the same Docker volume.
• Re-ran a no-server container boot with the revised sample shape and confirmed /ready returned ready: true.
• Confirmed the current published ghcr.io/tuist/kura:latest image does not contain /etc/kura/extensions/tuist.lua, matching the reported extension error and motivating the omit-or-mount guidance.
• Confirmed release publishing uses kura/Dockerfile.release, then updated it to copy ops/helm/kura/hooks/tuist.lua into /etc/kura/extensions/tuist.lua.

No GitHub comments yet.