docs: update guides to match dev setup guide

[swarna1101]

Summary by CodeRabbit

• Documentation
  • Simplified Docker deployment guides with environment variable-based configuration and updated commands.
  • Revised default parameter values and clarified configuration requirements across multiple sections.
  • Enhanced tracing documentation with automatic trace collection workflows.
  • Improved getting-started guides and FAQ with updated setup instructions and troubleshooting guidance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Ready	Preview	Comment	Dec 1, 2025 10:48am

[coderabbitai]

Walkthrough

This PR updates documentation across five guide files to align with infrastructure and naming changes. Changes include: replacing hard-coded Docker image tags with environment variable references (e.g., p2pnode:${P2P_NODE_VERSION-latest}), updating docker-compose command syntax and configuration paths, revising environment variable default values (LOG_LEVEL, API_PORT, IDENTITY_DIR, OPTIMUM_MESH_MIN, BOOTSTRAP_PEERS), rebranding gRPC client references from "gRPC client (with MessageTraceGossipSub or MessageTraceOptimump2p)" to "gRPC P2P client," and updating code example paths and troubleshooting guidance to reflect the new workflow for identity generation and container orchestration.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

• Multiple heterogeneous changes across 5 files: Each guide file contains different types of updates (variable substitutions, default value changes, rebranding, path corrections, workflow updates), requiring separate reasoning for each.
• Environment variable and default parameter updates: 03-parameters.md introduces several default value changes (PROXY_HTTP_PORT → PROXY_PORT, LOG_LEVEL, API_PORT, IDENTITY_DIR, OPTIMUM_MESH_MIN) that need verification for consistency with actual configuration.
• Workflow and tooling changes: 02-getting-started-docker.md and 05-faq-glossary.md contain substantive workflow updates (docker-compose command changes, make target introduction, environment variable interpolation) that require careful review for accuracy.
• Naming/branding consistency: 04-experiments.md introduces gRPC client rebranding across multiple sections; cross-referencing with actual code paths (e.g., grpc_p2p_client/cmd/single/main.go) is recommended.

Possibly related PRs

• Rename mumP2P to mump2p throughout documentation #31: Performs global renaming of "mumP2P" → "mump2p" references, which directly overlaps with this PR's documentation updates to gRPC client naming and protocol references.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Concurrency Safety	⚠️ Warning	Documentation PR recommends Go example code with critical concurrency safety violations including goroutine leaks, unbounded spawning, missing context cancellation propagation, unsafe os.Exit(), and write-after-close races.	Refactor Go examples with proper lifecycle management, context cancellation in receiver loops, worker pools for bounded concurrency, graceful shutdown instead of os.Exit(), and synchronized channel closure.

✅ Passed checks (7 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main objective of the pull request—updating documentation guides to align with the dev setup guide. It is directly related to the changeset covering five documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Go Build And Test Rationale	✅ Passed	No .go files modified; check applies only when code changes affect Go packages—condition not met.
Public Api Changes	✅ Passed	Documentation-only update to getoptimum/docs repository with no changes to source code, exported types, functions, interfaces, or public APIs.
Security Considerations	✅ Passed	Documentation-only pull request with no executable code. Properly guides users to generate cryptographic identities via make generate-identity, uses placeholder syntax for examples, and references .env files for secrets management. No SQL injection, command injection, path traversal, unvalidated inputs, hardcoded credentials, insecure crypto, or missing rate limiting vulnerabilities identified.
Rust Best Practices	✅ Passed	Rust best practices check is not applicable; PR contains only documentation markdown files with no Rust source code.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch update-docker-guide-from-dev-setup

---

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

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

docs/guides/03-parameters.md (1)

31-31: Normalize CLUSTER_ID usage between protocol mode examples.

Line 31 (RLNC mode) uses CLUSTER_ID=${CLUSTER_ID} (env interpolation), while line 69 (GossipSub mode) uses CLUSTER_ID=p2pnode-1 (literal value). For clarity and consistency, both should follow the same pattern.

Recommended fix: Use ${CLUSTER_ID} in both examples to align with the .env-driven configuration approach shown in the parameter defaults tables.

Apply this diff:

 p2pnode-1:
   image: 'getoptimum/p2pnode:${P2P_NODE_VERSION-latest}'
   environment:
     - NODE_MODE=gossipsub
     - LOG_LEVEL=debug
-    - CLUSTER_ID=p2pnode-1
+    - CLUSTER_ID=${CLUSTER_ID}
     - GOSSIPSUB_PORT=6060

Alternatively, add a note explaining that line 69 shows a literal example for illustration, while line 31 and the parameter defaults use env variables.

Also applies to: 69-69

docs/guides/02-getting-started-docker.md (2)

273-283: Clarify repository context for gRPC P2P client commands.

The commands reference ./grpc_p2p_client/p2p-client, which does not exist in this documentation repository. The referenced source code and executables are in the optimum-dev-setup-guide repository. Add a note indicating these commands should be run within that separate repository context.

---

163-167: Both referenced external file paths cannot be verified and appear to be incorrect.

The links to docker-compose-optimum.yml and docs/guide.md in the getoptimum/optimum-dev-setup-guide repository could not be found at the stated locations. Verify that:

• The repository name and structure are accurate
• The file paths exist at the referenced URLs
• The links are still accessible and haven't been moved or renamed

Consider updating the guide with verified links or linking directly to the Optimum docs site at https://docs.getoptimum.xyz/docs/guides/02-getting-started-docker if this content has been relocated.

📜 Review details

Configuration used: Repository: getoptimum/coderabbit/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ac324a9 and 5561b78.

📒 Files selected for processing (5)

• docs/guides/01-getting-started-cli.md (1 hunks)
• docs/guides/02-getting-started-docker.md (8 hunks)
• docs/guides/03-parameters.md (5 hunks)
• docs/guides/04-experiments.md (2 hunks)
• docs/guides/05-faq-glossary.md (3 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*

⚙️ CodeRabbit configuration file

**/*: When you find the same underlying issue in multiple locations (same pattern, same fix):

• Do NOT post separate comments for each occurrence.
• Post a single primary comment on the first occurrence.
• In that comment, include a short list of “Also at: file:line” references
  for the other locations (e.g. 'Also at: foo.go:42, bar.go:17').
  Prioritize signal over volume: one strong comment that references multiple
  locations is preferred over many near-identical comments.

Files:

• docs/guides/05-faq-glossary.md
• docs/guides/03-parameters.md
• docs/guides/02-getting-started-docker.md
• docs/guides/04-experiments.md
• docs/guides/01-getting-started-cli.md

**/*.md

⚙️ CodeRabbit configuration file

**/*.md: - Technical accuracy first; keep commands copy-pastable; prefer minimal prerequisites.

Files:

• docs/guides/05-faq-glossary.md
• docs/guides/03-parameters.md
• docs/guides/02-getting-started-docker.md
• docs/guides/04-experiments.md
• docs/guides/01-getting-started-cli.md

🪛 LanguageTool

docs/guides/02-getting-started-docker.md

[style] ~303-~303: The serial comma (Oxford comma, Harvard comma) is missing.
Context: ...ch nodes * Inside the proxy container, resolve and ping node hosts: ```sh docker-compose ...

(SERIAL_COMMA_ON)

docs/guides/01-getting-started-cli.md

[style] ~3-~3: Since ownership is already implied, this phrasing may be redundant.
Context: ...ct with Optimum Network without running your own infrastructure. In the next 5 minutes,...

(PRP_OWN)

🔇 Additional comments (7)

docs/guides/01-getting-started-cli.md (1)

3-3: Minor style note: Slightly redundant phrasing.

"Running your own infrastructure" is idiomatic and clear, though "own" is technically implied. This is acceptable as-is if you prefer conversational tone; no fix needed.

docs/guides/02-getting-started-docker.md (1)

99-106: Clear identity generation workflow with env variable integration.

The multi-step identity generation process (make generate-identity → copy BOOTSTRAP_PEER_ID → edit .env) is well-documented and aligns with the parameter defaults. Good alignment with updated dev setup workflow.

docs/guides/03-parameters.md (1)

98-98: Verify parameter defaults align across all guides.

Parameter defaults have been updated:

• LOG_LEVEL: debug (line 98)
• API_PORT: 9090 (line 101)
• IDENTITY_DIR: /identity (line 102)

Confirm these are used consistently across 02-getting-started-docker.md and 05-faq-glossary.md. A spot check shows they are present, but a comprehensive verification is recommended.

Also applies to: 101-101, 102-102

docs/guides/04-experiments.md (2)

115-115: Automatic trace collection narrative is well-integrated.

The explanation of automatic trace collection (lines 115, 125–129) clearly communicates the benefit and aligns well with the updated gRPC client naming and usage pattern. Good documentation of this feature.

Also applies to: 125-129

---

123-123: File path does not exist — review comment references non-existent documentation file.

The review comment references docs/guides/04-experiments.md, but this file does not exist in the repository. The cloned repository (github.com/getoptimum/optimum-dev-setup-guide) contains only docs/guide.md and no guides/ subdirectory. The verification request cannot proceed because the documented file path is incorrect.

Likely an incorrect or invalid review comment.

docs/guides/05-faq-glossary.md (2)

23-33: Identity generation workflow is clear and well-structured.

The two-option approach (Makefile target and script) with clear output description (./identity/p2p.key, BOOTSTRAP_PEER_ID) aligns well with the workflow in 02-getting-started-docker.md. Good documentation of the .env integration step.

---

106-114: Troubleshooting commands are consistent and well-structured.

The troubleshooting workflow (check logs, verify network, test health endpoints, check auth, verify versions, check service status) is practical and uses consistent docker-compose command syntax. The specific health endpoints (Proxy 8081, P2P Node 9091) align with parameter updates.