Install: Relocate multi-node/-zone setup instructions

[amotl]

About

Finalize dissolving the "Admin/Clustering" section, by relocating remaining content about multi-node and multi-zone setup instructions to "Install".

[coderabbitai]

Walkthrough

Documentation restructuring reorganizes admin and install sections, removing the standalone clustering page, updating navigation hierarchy, normalizing heading capitalization, and expanding configuration documentation with clearer environment variable guidance and path specifications.

Changes

Cohort / File(s)	Change Summary
Admin Documentation Restructuring docs/admin/clustering/index.md	Entire content removed, including clustering overview, rubric block, and toctree navigation entries.
Admin Documentation Restructuring docs/admin/index.md	Navigation restructured: replaced "Cluster" grid label with "Capacity Management," added Scaling reference, removed clustering/index link; updated production guidance text; increased toctree maxdepth from 1 to 2; revised scaling description and software upgrades wording.
Installation Documentation Restructuring docs/install/index.md	Added new toctree block for multi-node/multi-zone navigation; introduced admin-clustering rubric section with grid layout for cluster configuration cards; replaced Notes heading with rubric block containing deployment information.
Installation Documentation Restructuring docs/install/multi-node.md, docs/install/multi-zone.md	Normalized document titles from "CrateDB multi-node/multi-zone setup" to "Multi-node/Multi-zone setup."
Configuration Documentation Clarification docs/install/configure.md	Normalized heading capitalization; clarified configuration file location (/etc/crate); expanded environment variable guidance with /etc/default/crate path for vanilla packages and RPM-specific note for /etc/sysconfig/crate; added example environment variable snippet with heap size, locked memory, Java options, and IPv4 settings.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Navigation structural changes across multiple documentation index files require cross-referencing to ensure consistency
• Configuration documentation expansion includes new path specifications and environment variable examples that should be validated for accuracy
• Title and heading normalization changes are straightforward but spread across multiple files

Possibly related PRs

• Sharding and partitioning 101: Relocate to "performance guides" section #467: Modifies docs/admin/index.md navigation entries and reorganizes cluster-related content
• Admin: Relocate "Scale clusters up and down" to parent folder #468: Performs the same admin documentation reorganization with clustering page removal and scaling navigation updates
• Feature: Reorganize usage guide about logical replication (CCR) #466: Modifies docs/admin/clustering/index.md navigation structure and entries

Suggested labels

guidance

Suggested reviewers

• bmunkholm
• kneth
• surister

Poem

🐰 The docs now dance in harmony anew,
Clustering paths consolidated through and through,
Headings straightened, config made clear,
Multi-node routes now held dear,
Navigation flows with graceful ease! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Install: Relocate multi-node/-zone setup instructions" accurately reflects the primary objective of the changeset. The raw_summary shows that the changes involve removing the entire clustering documentation page (docs/admin/clustering/index.md), updating the admin index to remove clustering references and add scaling content, and relocating multi-node and multi-zone setup documentation to the install section. The title is concise, clear, and directly summarizes the main change from the developer's perspective without unnecessary noise or vagueness.
Description Check	✅ Passed	The pull request description "Finalize dissolving the "Admin/Clustering" section, by relocating remaining content about multi-node and multi-zone setup instructions to "Install"" is directly related to the changeset. It accurately describes the purpose and scope of the changes: removing the clustering section from the admin documentation structure and moving multi-node and multi-zone setup instructions to the install section. The description provides meaningful information that aligns with what the raw_summary shows across multiple modified files.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch install-setup-cluster

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/install/configure.md (1)

33-52: Example environment variables block enhances clarity and actionability.

The new code block with commented environment variable examples (CRATE_HEAP_SIZE, MAX_LOCKED_MEMORY, CRATE_JAVA_OPTS, CRATE_USE_IPV4) provides users with concrete configuration patterns and helps them understand typical tuning scenarios.

Line 5–6: Consider simplifying "In order to configure CrateDB, please take note of" to "To configure CrateDB, note the" for more concise phrasing.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d59d053 and 5a97acd.

📒 Files selected for processing (6)

• docs/admin/clustering/index.md (0 hunks)
• docs/admin/index.md (2 hunks)
• docs/install/configure.md (2 hunks)
• docs/install/index.md (2 hunks)
• docs/install/multi-node.md (1 hunks)
• docs/install/multi-zone.md (1 hunks)

💤 Files with no reviewable changes (1)

• docs/admin/clustering/index.md

🧰 Additional context used

🧠 Learnings (9)

📚 Learning: 2025-08-14T19:02:43.308Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 253
File: docs/integrate/mindsdb/index.md:21-33
Timestamp: 2025-08-14T19:02:43.308Z
Learning: In CrateDB integration documentation examples, default connection parameters (user="crate", password="", host="127.0.0.1") are intentionally used to provide working out-of-the-box examples for users with local CrateDB instances, rather than using placeholder values that require customization.

Applied to files:

• docs/install/index.md
• docs/install/configure.md

📚 Learning: 2025-10-06T16:40:16.322Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-10-06T16:40:16.322Z
Learning: In the crate/cratedb-guide repository, documentation is organized by content type: files in `docs/feature/`, `docs/integrate/`, and `docs/ingest/` are reference material designed for quick access, while `docs/start/` contains learning path content. Reference material sections use top-right reference layouts for efficient navigation.

Applied to files:

• docs/install/index.md
• docs/install/configure.md
• docs/admin/index.md

📚 Learning: 2025-10-30T23:12:30.165Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 465
File: docs/admin/troubleshooting/system-tables.md:6-6
Timestamp: 2025-10-30T23:12:30.165Z
Learning: In the cratedb-guide repository, documentation headers and titles should use sentence case (e.g., "Diagnostics with system tables") rather than title case (e.g., "Diagnostics with System Tables"). This style choice enables headers to be referenced more fluently within sentences.

Applied to files:

• docs/install/configure.md

📚 Learning: 2025-09-25T19:31:54.320Z

Learnt from: bmunkholm
Repo: crate/cratedb-guide PR: 340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Applied to files:

• docs/admin/index.md

📚 Learning: 2025-08-09T11:00:03.578Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 236
File: docs/index.md:312-316
Timestamp: 2025-08-09T11:00:03.578Z
Learning: In the CrateDB Guide documentation, locally stale references (such as `(reference-architectures)=`, `(domain)=`, and similar anchor labels) should be retained even when they appear unused within the repository, as external projects might still reference them. This ensures backward compatibility for external documentation and projects.

Applied to files:

• docs/admin/index.md

📚 Learning: 2025-08-14T11:40:39.584Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 249
File: docs/ingest/etl/index.md:30-31
Timestamp: 2025-08-14T11:40:39.584Z
Learning: In the CrateDB Guide documentation, the project policy is to prune ALL legacy aliases (like `(apache-airflow)=`, `(aws-*)=`) and fix forward if anything breaks, rather than maintaining backward compatibility with dual anchors.

Applied to files:

• docs/admin/index.md

📚 Learning: 2025-08-22T18:11:12.776Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 263
File: docs/integrate/kafka/docker-python.md:112-120
Timestamp: 2025-08-22T18:11:12.776Z
Learning: In documentation and tutorial repositories like cratedb-guide, code examples should prioritize simplicity, clarity, and educational value over production-ready features. Comprehensive error handling, extensive validation, and other production concerns can distract from the main learning objectives and make examples harder to follow. Review suggestions should focus on correctness and clarity rather than production hardening.

Applied to files:

• docs/admin/index.md

📚 Learning: 2025-08-09T21:40:46.154Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 238
File: docs/integrate/streamsets/index.md:18-21
Timestamp: 2025-08-09T21:40:46.154Z
Learning: In the CrateDB Guide documentation, reStructuredText files (`.rst`) use the RST label syntax `.. _label:` while MyST Markdown files (`.md`) use the syntax `(label)=`. Both formats are used throughout the repository and labels can be cross-referenced between them.

Applied to files:

• docs/admin/index.md

📚 Learning: 2025-08-23T15:09:38.537Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 235
File: docs/start/index.md:1-3
Timestamp: 2025-08-23T15:09:38.537Z
Learning: In the CrateDB Guide documentation, the `(use)=` label in `docs/start/index.md` is intentionally placed alongside `(getting-started)=` as part of the documentation architecture, even though it may appear to conflict with top-level "Use" section labeling. This is a deliberate design decision by the maintainers.

Applied to files:

• docs/admin/index.md

🪛 LanguageTool

docs/install/configure.md

[style] ~4-~4: Consider a more concise word here.
Context: ...-configure)= # Configuration settings In order to configure CrateDB, please take note of ...

(IN_ORDER_TO_PREMIUM)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build docs

🔇 Additional comments (8)

docs/install/multi-zone.md (1)

3-3: Header normalization is consistent with restructuring goals.

The title change aligns with the multi-node.md header change and sentence-case style convention, removing the redundant "CrateDB" prefix while preserving the anchor label for cross-references.

docs/install/multi-node.md (1)

3-3: Header normalization is consistent with multi-zone.md and restructuring goals.

The title change aligns with sentence-case style convention and mirrors the multi-zone.md update, while preserving the anchor label for cross-references.

docs/install/index.md (2)

25-30: New toctree properly integrates multi-node and multi-zone into navigation hierarchy.

The hidden toctree with maxdepth: 1 ensures multi-node and multi-zone documentation are registered in the build system and accessible for cross-references (as used in the rubric grid below).

---

147-182: Cluster configuration rubric section is well-structured and clearly contextualizes deployment scenarios.

The new rubric section with grid-item-card layout provides visual navigation to Multi-node and Multi-zone setup guides, with appropriate descriptive text. Grid styling is consistent with the installation grid above (lines 46–141). The anchor label (admin-clustering)= aligns with consolidating clustering-related guidance under the Install section.

Please verify that the grid-item-card links resolve correctly during documentation build by confirming that multi-node-setup and multi-zone-setup references match the anchor labels in docs/install/multi-node.md and docs/install/multi-zone.md.

docs/install/configure.md (2)

3-3: Heading case normalization aligns with sentence-case style convention.

All three section headings are normalized to sentence case ("Configuration settings," "Configuration files," "Environment variables"), consistent with the documented style in PR 465 and improving fluency within sentence contexts.

Also applies to: 8-8, 18-18

---

12-12: Configuration paths and environment variable guidance are now explicit and comprehensive.

Added clarification that package-based installations locate configuration in /etc/crate, while tarball and Windows setups use relative paths. The expanded environment variables section now explicitly references /etc/default/crate for vanilla package setups and includes a helpful RPM legacy note (versions ≤5.2.11, 5.3.8, 5.4.7, 5.5.2 using /etc/sysconfig/crate). This significantly improves user onboarding and troubleshooting.

Also applies to: 20-27

docs/admin/index.md (2)

26-26: Navigation labels and descriptions are updated to reflect content reorganization and improve clarity.

Changes across lines 26, 29, 36, and 46 consolidate the clustering guidance relocation: "Cluster" → "Capacity Management" clarifies the card's scope (scaling operations), and descriptions are refined to be more concise and action-oriented. The navigation path from "Clustering" to "Scaling" properly reflects that clustering content has moved to the Install section.

Verify that docs/scale/index.md exists and is properly structured with maxdepth: 2 in the toctree, ensuring the new "Scaling" card navigation resolves correctly and the deeper hierarchy is accessible.

Also applies to: 29-29, 36-36, 46-46

---

31-31: Increased maxdepth from 1 to 2 enables deeper navigation within Scaling section.

The change to maxdepth: 2 appropriately accommodates the likely structure of scaling-related subsections and aligns with the Software Upgrades section (which uses maxdepth: 2 at line 41).