docs: restricted-environment install runbook (#692 part 3)

.wiki/Deployment-and-Security.md

@@ -20,6 +20,14 @@ including a node killed mid-run. The release bundle ships `deploy/` (install.sh,
 uninstall.sh, lib/) for use with `--artifact`. One installer at a time (no lock);
 `--ddl-timeout` must be >= 1; the password reaches only `clickhouse-client`.
 
+The operator runbook for restricted environments (#692 part 3) is
+[`docs/HOSTED-INSTALL.md`](../docs/HOSTED-INSTALL.md): preflight decision table and SQL,
+tested grants as `GRANT` statements, self-managed / HTTPS-only / Altinity Cloud / clickhouse-operator
+examples (the last two are **not tested end to end**), topology, scale-out and retry, handler
+verification. If `http_handlers` cannot be pushed, ClickHouse-native hosting is impossible: use the Caddy
+image or Helm chart below. `--cluster` takes the literal name from `system.clusters` (the `{cluster}` macro
+is rejected).
+
 ## Authentication modes
 
 - Native/Bearer OAuth for ClickHouse variants with token processors and ephemeral

.wiki/Source-Map.md

@@ -42,6 +42,7 @@ Back to [[Home]]. Related: [[Architecture]], [[Product-and-Features]].
 - [`docs/ADR-0004-ui-shell.md`](../docs/ADR-0004-ui-shell.md) — the #577 Preact evaluation and its RETAIN-vanilla outcome.
 - [`docs/V2-UX-HANDOVER.md`](../docs/V2-UX-HANDOVER.md) — shipped-UX + committed-contract inventory for the V2 redesign (#582).
 - [`docs/DEPLOYMENT.md`](../docs/DEPLOYMENT.md) — deployment sequence.
+- [`docs/HOSTED-INSTALL.md`](../docs/HOSTED-INSTALL.md) — restricted-environment install runbook (#692); [`docs/ASSET-DISTRIBUTION.md`](../docs/ASSET-DISTRIBUTION.md) is the mechanism.
 - [`docs/LOGIN-SCREEN.md`](../docs/LOGIN-SCREEN.md) — login configuration.
 - [`CHANGELOG.md`](../CHANGELOG.md) — released and unreleased behavior.
 - [`docs/ui-snapshots/CAPTURE-SPEC.md`](../docs/ui-snapshots/CAPTURE-SPEC.md) — visual baseline.

CHANGELOG.md

@@ -10,6 +10,13 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
 ## [Unreleased]
 
 ### Added
+- **#692 (part 3): restricted-environment install runbook, `docs/HOSTED-INSTALL.md`.** Preflight
+  decision table and copy-paste preflight SQL (grants, clusters, `file()` write/read/truncate probe,
+  interserver auth, egress), tested grants as `GRANT` statements per mode, end-to-end examples (self-managed,
+  HTTPS-only, Altinity Cloud, clickhouse-operator; the last two clearly marked not tested end to end),
+  topology/scale-out/retry procedures, handler enablement and verification, Option B as a described
+  alternative. README, DEPLOYMENT.md, ASSET-DISTRIBUTION.md, `docs/deployment.html` and the wiki link to it;
+  `docs/deployment.html` no longer describes the container image as the Python runner (it is Caddy).
 - **#692 (part 2): `deploy/install.sh --cluster` now works on multi-replica clusters.**
   SQL-only, two-phase install with server-side fan-out: preflight, pre-clean,
   phase 1 to `_asb_next_*` (upload once and copy, or `--pull-url`), per-node length

README.md

@@ -665,6 +665,8 @@ verify), and checks each node's length and SHA-256; re-run it after a scale-out.
 `deploy/uninstall.sh` empties the files. Cross-node reads need the cluster's `<secret>`
 (or per-replica credentials), run one installer at a time, and the deploy user needs a few grants — see
 [docs/ASSET-DISTRIBUTION.md](docs/ASSET-DISTRIBUTION.md#installing-with-deployinstallsh).
+Restricted environments (Altinity Cloud, clickhouse-operator, no filesystem access, HTTP-only): see the
+runbook [docs/HOSTED-INSTALL.md](docs/HOSTED-INSTALL.md).
 
 With **no** `--audience`, the IdP returns an **id_token** (its `aud` is the
 client_id) and the browser sends that as the bearer — so ClickHouse's
@@ -763,7 +765,7 @@ deploy/k8s/   sample Deployment, Service, ConfigMap, Ingress example
 helm/         published Helm chart source
 tests/        vitest + happy-dom, one spec per module
 docs/         DEVELOPMENT.md, ARCHITECTURE.md, DEPLOYMENT.md,
-              ASSET-DISTRIBUTION.md, CLICKHOUSE-OAUTH.md, CLICKHOUSE-OSS-OAUTH.md
+              ASSET-DISTRIBUTION.md, HOSTED-INSTALL.md, CLICKHOUSE-OAUTH.md, CLICKHOUSE-OSS-OAUTH.md
 ```
 
 ## Supported browsers

docs/ASSET-DISTRIBUTION.md

@@ -7,7 +7,9 @@ one; this document is about the native mode.) That makes "how do the asset bytes
 real design question on a multi-node cluster, because **ClickHouse does not
 replicate the `user_files/` directory**: it is a node-local folder.
 
-This doc explains the trade-offs and what `deploy/install.sh` ships.
+This doc explains the trade-offs and what `deploy/install.sh` ships. The operator procedure for restricted
+environments (preflight, tested grants, Altinity Cloud / clickhouse-operator examples, scale-out) is the
+runbook [HOSTED-INSTALL.md](HOSTED-INSTALL.md); this page stays the mechanism and design reference.
 (A `docs/sql.html` mirror is also published to GitHub Pages on every tagged
 release, for an unauthenticated try-it-now demo — see `release.yml` — but
 that's a separate distribution channel from the cluster-serving problem
@@ -84,7 +86,7 @@ serve it with the same `file://` static handler.
   build), which is too large for several channels: clickhouse-operator
   `spec.configuration.files` lands in a Kubernetes ConfigMap, which is capped at
   1 MiB, and control planes that push settings inline (for example, ACM's
-  setting-push has an ~8 KB URI limit) cannot carry it either. In practice it
+  setting-push is reported to have a small, ~8 KB URI limit; **unverified**) cannot carry it either. In practice it
   has to be a file delivered by some other mechanism (image layer, volume,
   init container), not an inline config value.
 
@@ -262,7 +264,7 @@ before the run (the preflight rejects it), a node **killed mid-run** right after
 never an empty or partial file; the queued DDL replay settles; a re-install converges every node on the new one), an unreachable pull URL, missing `REMOTE` / `URL`
 grants, a single node, and uninstall. Images (exact tags): `clickhouse/clickhouse-server:26.3.18.32` and
 `altinity/clickhouse-server:25.8.33.20001.altinityantalya`, with `clickhouse/clickhouse-keeper:25.8.33.6` (CI; locally `clickhouse-keeper:25.8` works too).
-**Not covered:** the real GitHub release URL, TLS (`--secure`) against a live server, and the
+**Not covered:** the real GitHub release URL through the installer (a single-node `url()` download of it was probed by hand, see HOSTED-INSTALL.md), TLS (`--secure`) against a live server, and the
 per-replica-credentials interserver path. The script logic (strict row checks, cleanup, the
 password's reach) is additionally unit-tested against a simulator.
 

docs/DEPLOYMENT.md

@@ -7,7 +7,9 @@ There are now two distinct deployment surfaces:
 2. **Containerized runtime** — run the static SPA image in Docker or Kubernetes
    for local or shared use, with browser requests sent directly to ClickHouse.
 
-This document focuses on the first mode. For source development, Docker, and
+This document focuses on the first mode. If you cannot touch the server filesystem (Altinity Cloud,
+clickhouse-operator, other managed clusters) or run a multi-node cluster, follow the runbook
+[HOSTED-INSTALL.md](HOSTED-INSTALL.md) (preflight, tested grants, examples, scale-out). For source development, Docker, and
 Kubernetes/Helm instructions, see [DEVELOPMENT.md](DEVELOPMENT.md).
 
 The app is three things on the target ClickHouse: