Chainstack Self-Hosted Documentation Audit
The reference content is detailed and the failure-mode docs (login, troubleshooting) are genuinely good — but a major architectural change (v2.0.0 retiring Helm) landed in the changelog and never propagated to the install, upgrade, requirements, or environment pages, and the hardware numbers disagree across three pages. An operator following the docs today will install a dependency the product no longer uses and read minimums that contradict each other.
1. v2.0.0 retired Helm, but every operational page still mandates it (critical)
Location: /docs/self-hosted/requirements, /docs/self-hosted/installation, /docs/self-hosted/advanced-installation, /docs/self-hosted/upgrade, /docs/self-hosted/environment-setup, /docs/self-hosted/quick-start, /docs/self-hosted/uninstallation
Problem: The v2.0.0 release (May 13, 2026) "retires Helm from the deployment path in favor of a typed in-process provisioning pipeline backed by Server-Side Apply." Yet the System requirements page — last modified May 21, 2026, eight days after that release — still lists Helm | v3.x or later | Required for installation. The Installation prerequisites still say "make sure you have a running Kubernetes cluster with kubectl, Helm, yq, and openssl installed." Environment setup still dedicates a section reading "Helm is the package manager used to deploy Chainstack Self-Hosted." The Upgrade page still says "Helm automatically rolls back to the previous revision." Quick start still installs Helm as step 1 and shows the preflight line "Checking helm version (v3+ required)." Uninstallation still says "This removes the Helm release." The Advanced installation flag table is entirely Helm-framed: --set = "Set Helm values," --dry-run = "Print Helm command without executing," -r, --release = "Helm release name," --chart-registry = "OCI registry URL."
Consequence: An operator on the current version reads contradictory truths from the canonical pages versus the changelog. They will install and verify a tool the product no longer uses, trust a rollback mechanism ("Helm automatically rolls back") that may no longer exist, and try to reason about deployments through a "Helm release" abstraction that has been replaced by label-scoped Server-Side Apply. For AI coding agents this is worse: an agent parsing the requirements page (the most authoritative-looking, most recently edited page) will confidently emit Helm setup steps with no signal that they're obsolete.
The fix: Treat the v2.0.0 changelog as the source of truth and reconcile every operational page to it. Remove Helm from System requirements software prerequisites (or downgrade it to "no longer required as of v2.0.0"), rewrite the Advanced installation flag descriptions to describe the typed provisioning pipeline instead of Helm values/releases, and correct the Upgrade page's rollback claim. Add a dated "as of v2.0.0" banner to any page that can't be rewritten immediately.
2. Control Panel minimum hardware contradicts itself across three pages (critical)
Location: /docs/self-hosted/faq vs /docs/self-hosted/requirements and /docs/self-hosted/evaluation-setup
Problem: Three pages state different minimums for the same thing. Evaluation setup: Control Panel = 5 cores / 6 GiB / 15 GB. System requirements: Control Panel = 5 cores / 6 GiB / 15 GB. FAQ: Control Panel = 6 CPU cores, 8 GiB RAM, 15 GB. The combined "Control Panel + Ethereum Mainnet (Light)" example is also split: System requirements totals it to 9 cores / 22 GiB, while the FAQ states 10 CPU cores, 24 GiB RAM.
Consequence: An operator provisioning a server (or a VPS, given the Contabo/Ubuntu example in Quick start) sizes the box from whichever page they land on. Land on the FAQ and over-provision by a core and 2 GiB; land on the FAQ for the combined node and provision 10/24 when the requirements page says 9/22. For tight evaluation environments where "the cumulative pod resource requests set a real floor" (per Evaluation setup), the gap between 5/6 and 6/8 is exactly the kind of margin that decides whether cpctl install reaches Healthy.
The fix: Pick one authoritative source (System requirements) for all hardware numbers and have the FAQ and Evaluation setup link to it rather than restate values. Correct the FAQ's 6/8 and 10/24 figures to match (5/6 and 9/22), or document explicitly why the FAQ's numbers differ if they intentionally include headroom.
3. The v2.0.0 breaking-change upgrade procedure exists only in the changelog (critical)
Location: /docs/self-hosted/upgrade vs /docs/self-hosted/changelog/chainstack-self-hosted-v2-0-0-may-13-2026
Problem: Upgrading to v2.0.0 has a hard breaking change: "Before upgrading to v2.0.0, remove existing node deployments from the Control Panel. After the upgrade completes, redeploy the nodes" — because pre-v1.9.0 nodes "were created under Helm release ownership and are not tracked by the new label-scoped reconciler." This instruction lives only in the release notes and the v2.0.0 changelog. The Upgrade page — the page an operator actually opens to upgrade — still walks through a pre-v2.0.0 v1.7.1 → v1.8.0 plan and frames rollback around Helm, with no mention of removing node deployments first.
Consequence: An operator following the Upgrade page upgrades in place without removing deployments, and their nodes "may misbehave under the new reconciler." This is a data/availability risk presented by the docs as a routine in-place upgrade. The MaxMajorJump preflight check is listed on the Upgrade page but the page never explains what the operator must do when a major jump (v1.x → v2.0.0) is the thing being attempted.
The fix: Promote the v2.0.0 breaking-change steps into the Upgrade page as a prominent, version-gated callout: "Upgrading from v1.9.0 or earlier? Remove all node deployments before upgrading, then redeploy." Update the example upgrade plan to a current version pair and reconcile the rollback description with the new pipeline.
4. New v2.0.0 configuration env vars are documented only in the changelog (significant)
Location: /docs/self-hosted/changelog/chainstack-self-hosted-v2-0-0-may-13-2026 (absent from /docs/self-hosted/installation, /docs/self-hosted/advanced-installation, /docs/self-hosted/troubleshooting)
Problem: v2.0.0 introduced two operational tunables that bound bootstrap polling: BOLT_INITIAL_PRESENCE_TIMEOUT (default 5m) and BOLT_DISAPPEARANCE_TIMEOUT (default 1m). They appear nowhere except the changelog — not in the Advanced installation reference, not in the install flow, and not in Troubleshooting, where a "volumes failed to appear" timeout is exactly the symptom an operator would search for.
Consequence: An operator hitting a bootstrap hang on slow-provisioning storage has no documented knob to extend the timeout, because the only mention is buried in a per-release changelog they have no reason to read. Agents indexing the reference pages will never surface these variables.
The fix: Add both variables to the Advanced installation configuration reference and cross-link them from the Troubleshooting section on stuck/failed deployments, with the default values and what each controls.
5. Install examples hard-code "Version: v1.8.0" while the installer defaults to latest (significant)
Location: /docs/self-hosted/installation, /docs/self-hosted/advanced-installation, /docs/self-hosted/download-installer, /docs/self-hosted/quick-start
Problem: Multiple pages show installer output pinned to Version: v1.8.0. But the v1.8.0 changelog states cpctl install "now defaults to the latest available chart version when you omit -v" — and the latest is now v2.0.0. So the static "v1.8.0" in every example is stale, and worse, it predates the Helm-retirement boundary.
Consequence: Readers anchor on v1.8.0 as "the version," reinforcing the obsolete Helm-based mental model and obscuring that a default install now pulls v2.0.0 (no Helm, breaking-change reconciler). Anyone copy-pasting expecting v1.8.0 output will see different output and may assume something went wrong.
The fix: Replace pinned version strings in example output with a placeholder like vX.Y.Z (latest) or annotate that the installer resolves the latest version by default. Audit all four pages for the literal v1.8.0.
6. FAQ describes "sync from genesis, 2–5 days" though every preset is snapshot-only (significant)
Location: /docs/self-hosted/faq
Problem: The FAQ answer to "How long does initial node sync take?" leads with "With standard sync from genesis, expect 2–5 days for Ethereum Mainnet." But the very next FAQ entry says "all current presets ship with snapshot bootstrap pre-configured," and Deploying nodes confirms "both presets currently ship... with snapshot bootstrap pre-configured — the node downloads a pre-built chain snapshot rather than syncing from genesis." There is no shipped path that syncs from genesis.
Consequence: A reader budgets 2–5 days of sync time for a scenario the product no longer offers, and may believe they need to choose or configure snapshot mode when it's already the only behavior. The "standard" framing implies genesis sync is the default, which is backwards.
The fix: Rewrite the answer to lead with the actual behavior — snapshot bootstrap reduces sync to hours — and drop or clearly label the genesis-sync figure as historical/not-applicable to current presets.
7. The installer's documented --yes default triggers the most common login failure (significant)
Location: /docs/self-hosted/advanced-installation and /docs/self-hosted/troubleshooting
Problem: Troubleshooting states the most common cause of "Login failed" is the backend URL being set to an in-cluster address "your browser cannot resolve," and that "This happens when the installer runs with --yes or when you press Enter at the backend URL prompt, accepting the in-cluster default." Yet the Advanced installation flag reference lists -y, --yes ("Auto-approve prompts (non-interactive)") and --backend-url (default http://<release>-cp-deployments-api) with no warning that the non-interactive path lands you in the single most common failure mode.
Consequence: Operators who run a non-interactive install — the natural choice for automation and the exact thing --yes exists for — get a Control Panel they can't log into, and only discover why if they happen to find the Troubleshooting page. The default flag behavior and the most-documented failure are causally linked but never cross-referenced at the point of use.
The fix: Add a warning on the --yes / --backend-url flags (and in the install flow) that a non-interactive install must set --backend-url to a browser-reachable address, with a link to the Troubleshooting entry.
8. One CLI-download page has three different names (minor)
Location: /docs/self-hosted/download-installer (referenced from /docs/self-hosted/introduction and /docs/self-hosted/installation)
Problem: The same destination page (/docs/self-hosted/download-installer) is labeled "Download Self-Hosted CLI" in the sidebar and page title, "Install the Self-Hosted CLI" in the Introduction page's body link, and "Download Chainstack Self-Hosted" from the Installation page. Three names for one page.
Consequence: Readers (and agents resolving cross-references) can't tell whether these point to the same step or three different ones — and "Install the CLI" vs "Download the CLI" vs "Download Chainstack Self-Hosted" each imply a different scope of action.
The fix: Standardize on one canonical name for the page and use it consistently in the sidebar, title, and every inbound link.
9. The Introduction never states the product is GA / production-ready (minor)
Location: /docs/self-hosted/introduction
Problem: v1.8.0 (May 4, 2026) marked General Availability and the FAQ confirms "Chainstack Self-Hosted is generally available and supports production deployments." But the Introduction — the first page a reader sees — makes no mention of GA or production-readiness; it reads as if maturity status is unknown.
Consequence: A reader evaluating whether to trust this for production has to dig into the FAQ or release notes to learn it's GA, when that's exactly the signal an introduction should carry.
The fix: State the GA status and supported production networks (Mainnet, Sepolia, Hoodi) in the Introduction, with a link to the release notes.
10. "Managing nodes" exposes only Delete, despite implying lifecycle control (minor)
Location: /docs/self-hosted/managing-nodes
Problem: The page title promises node management, but the Settings tab's only documented action is "Delete node — Permanently remove the node and its data." There is no documented start, stop, restart, or reconfigure operation.
Consequence: An operator expecting basic lifecycle control reads a page that offers exactly one destructive action and no way to pause or restart a node, with no statement that these operations are intentionally unavailable.
The fix: Either document the other lifecycle operations if they exist, or add an explicit note that delete-and-redeploy is currently the only supported management action (which would also dovetail with the v2.0.0 redeploy guidance).
11. First-login walkthrough has empty image placeholders (minor)
Location: /docs/self-hosted/first-login
Problem: The page contains lead-ins with no following content, e.g. "You'll see the Chainstack Self-Hosted login page:" with no rendered screenshot or text after it.
Consequence: A first-time operator following a step-by-step login guide hits a sentence that promises a visual and then shows nothing, breaking the walkthrough at the exact moment they need confirmation they're on the right screen.
The fix: Restore the missing screenshots or replace the dangling lead-ins with described text so the step is complete without the image.
What they do well
- The Troubleshooting page is genuinely strong: it names the single most common login failure, gives the exact
kubectlcommand to confirm it, and explains the root cause (in-cluster vs browser-reachable backend URL). - Reference data is precise where it exists — exact client versions (Reth v1.11.3, Prysm v7.1.3), per-preset CPU/RAM/storage tables, and concrete endpoint ports (8545/8546/5052).
- Release notes and changelog entries are clear and dated, including explicit breaking-change callouts — the problem is that the rest of the docs haven't caught up to them.
Top 3 recommendations
- Reconcile the entire doc set to v2.0.0. Remove/flag Helm everywhere (requirements, install, upgrade, environment, quick start, uninstall, advanced flags) and surface the breaking-change upgrade steps on the Upgrade page itself, not just the changelog.
- Establish one source of truth for hardware numbers and make the FAQ and Evaluation pages link to System requirements instead of restating contradictory minimums (5/6 vs 6/8, 9/22 vs 10/24).
- Stop documenting from stale snapshots: replace hard-coded
v1.8.0examples, fix the FAQ's genesis-sync answer, and pull the v2.0.0BOLT_*timeout variables into the reference and troubleshooting pages.