[features] add dedicated private server docs and introduce worker

[capcom6]

Summary by CodeRabbit

• Documentation
  • Added comprehensive Private Server feature documentation covering architecture overview, installation methods, configuration options, and operational best practices.
  • Enhanced Getting Started guide with improved architecture diagrams and Docker-focused setup instructions with better organization and reverse proxy guidance.

[coderabbitai]

Walkthrough

This PR adds comprehensive documentation for the Private Server feature, introducing a new dedicated documentation page and reorganizing the getting-started guide. Updates include architecture diagrams, deployment instructions, configuration examples, and operational guidance, along with navigation configuration changes.

Changes

Cohort / File(s)	Change Summary
New Private Server Feature Documentation docs/features/private-server.md	New file documenting Private Server architecture, prerequisites, installation methods (Docker, source, Helm), reverse proxy configuration, background worker setup, monitoring, and operational best practices with code examples and security notes.
Updated Getting-Started Guide docs/getting-started/private-server.md	Replaced architecture diagram with inline Mermaid flowchart, expanded prerequisites section, reorganized deployment instructions to Docker-first approach, standardized configuration block annotations, updated health check and credential verification sections, added reference link to comprehensive Private Server documentation.
Navigation Configuration mkdocs.yml	Added new navigation entry "Private Server: features/private-server.md" under Features section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Documentation changes are homogeneous in nature with consistent restructuring patterns
• Review focus areas: verify getting-started reorganization maintains logical flow, confirm Mermaid diagram accuracy, validate all code examples and configuration snippets are correct and consistent

Possibly related PRs

• Restructure private server and CA docs and update mkdocs config #76: Restructures docs/getting-started/private-server.md and updates mkdocs navigation, directly addressing the same documentation files and nav configuration.
• [getting-started] add Helm deployment example #147: Modifies docs/getting-started/private-server.md and handles Helm deployment content, overlapping with deployment instruction changes in this PR.
• [getting-started] add instructions to run the Private server w/o Docker #94: Updates deployment instructions for running the Private Server, addressing similar deployment methodology documentation that this PR reorganizes.

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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "[features] add dedicated private server docs and introduce worker" accurately summarizes the main changes in the changeset. The PR adds a new comprehensive documentation page (docs/features/private-server.md), updates the existing private server getting-started guide, and updates the mkdocs.yml navigation to include the new feature. The title's mention of "dedicated private server docs" directly corresponds to these documentation additions, and "introduce worker" aligns with the worker configuration content being documented in these files. The title is concise, clear, and specific without vague terminology or unnecessary noise.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch features/private-server-worker

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 945a7b6 and b3d8a42.

⛔ Files ignored due to path filters (1)

• docs/assets/private-server-arch.png is excluded by !**/*.png

📒 Files selected for processing (3)

• docs/features/private-server.md (1 hunks)
• docs/getting-started/private-server.md (7 hunks)
• mkdocs.yml (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

docs/getting-started/private-server.md

43-43: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

43-43: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

docs/features/private-server.md

43-43: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

43-43: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

---

145-145: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

---

190-190: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

🔇 Additional comments (9)

docs/getting-started/private-server.md (4)

7-46: Consider moving Mermaid diagram language specification review.

The architecture diagram is well-structured and informative for getting-started context. However, static analysis hints suggest the Mermaid code block at line 8 lacks proper language specification despite appearing correct in the source. This may indicate a linting configuration issue or markdown parsing edge case. Verify the build output to ensure Mermaid rendering works as expected.

---

56-92: Good: Docker-first guidance with clear configuration path.

The emphasis on Docker with fallback to features documentation is appropriate for getting-started context. The CONFIG_PATH callout at lines 90-92 is helpful for operators needing custom paths. Configuration example is clear with inline annotations.

---

94-112: Good: Clear step-by-step Docker launch with optional worker.

The three-step Docker approach (server setup, launch, optional worker) is logical and user-friendly. The reference to features/private-server.md#background-worker at line 112 provides appropriate depth for users wanting more worker details without cluttering the getting-started guide.

---

124-124: Good: Effective cross-referencing to comprehensive documentation.

The links to features/private-server.md for reverse proxy configuration (line 124) and the See Also section (lines 171-174) create a logical information hierarchy: getting-started for quick setup, features for operational depth. The additional resources (Ubuntu/Docker/Nginx guide, Docker Compose quickstart) are helpful.

Also applies to: 171-174

mkdocs.yml (1)

52-52: Good: Navigation entry properly integrated.

The Private Server entry is correctly placed at the top of the Features section and follows the file's indentation and linking conventions. This positioning promotes discoverability of the new feature documentation.

docs/features/private-server.md (4)

6-44: Consider addressing static analysis hints for Mermaid code block.

Like the getting-started file, the Mermaid diagram at line 6-43 properly specifies "mermaid" as the language, yet static analysis hints suggest MD040/MD046 violations. This appears to be a false positive in the linting configuration. Verify that the build process renders Mermaid diagrams correctly and that no actual code block formatting issues exist.

---

46-131: Excellent: Comprehensive multi-method installation with clear prerequisites.

The tabbed interface for Prerequisites (Docker/Sources/Helm) and Installation Methods provides excellent usability. The progression from simplest (Docker) to most complex (Helm) is logical. Helm security warning at lines 122-129 is appropriately detailed and protects users from committing secrets. Links to external resources (Helm Chart Documentation) are helpful.

---

133-153: Good: Reverse proxy guidance with appropriate depth levels.

Example Nginx configuration (lines 137-143) covers basics. Advanced Configuration section (lines 145-153) lists practical considerations (HTTP/2, timeouts, security headers, rate limiting, SSE proxying) without overwhelming beginners. This two-tier approach aligns well with the documentation hierarchy.

---

155-230: Excellent: Comprehensive worker documentation with operational guidance.

The Background Worker section is well-structured:

• Clear task descriptions (lines 159-161)
• Multiple launch methods matching installation patterns (lines 165-184)
• Complete configuration reference (lines 190-209)
• Prometheus metrics with alert thresholds (lines 211-223)
• Best practices emphasizing zero-downtime updates and lock management (lines 225-230)

This level of detail is appropriate for feature documentation and supports production deployments.

---

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.}