Add comprehensive documentation: quick start, tutorials, user manual, reference#63
Add comprehensive documentation: quick start, tutorials, user manual, reference#63renecannao merged 2 commits intomasterfrom
Conversation
Complete reference covering every Configuration struct field with types and defaults, all CLI commands grouped by section, all v1 API endpoints, all v2 API endpoints, ProxySQL integration details, and observability (Prometheus metrics, health endpoints, Graphite).
… reference New documentation (3,144 lines total): - docs/quickstart.md (132 lines) — 5-minute quick start guide - docs/tutorials.md (499 lines) — 4 step-by-step tutorials: 1. Setting up orchestrator with MySQL topology 2. Configuring ProxySQL failover hooks 3. Monitoring with Prometheus 4. Using the API v2 - docs/user-manual.md (1,148 lines) — 10-chapter user manual covering installation, discovery, failure detection, recovery, ProxySQL, observability, HA deployment, API usage, and troubleshooting - docs/reference.md (1,365 lines) — complete reference for every config field, CLI command, and API endpoint Updated docs/toc.md with "Getting Started" section linking all new docs.
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughFour new comprehensive documentation files were added to the docs directory: a quick start guide for initial setup, a reference manual covering configuration and API endpoints, step-by-step tutorials for common workflows, and a complete user manual covering architecture, deployment, and operations. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a substantial amount of new documentation to the project, significantly enhancing the resources available to users. The additions aim to streamline the onboarding process for new users and provide in-depth information for experienced operators, covering everything from initial setup and practical workflows to detailed configuration and API references. This comprehensive documentation suite will improve the overall user experience and reduce the learning curve for interacting with orchestrator. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
There was a problem hiding this comment.
Pull request overview
Adds a large set of new Markdown documentation intended to provide a Quick Start, tutorials, a user manual, and a comprehensive reference for orchestrator’s configuration/CLI/API surface area.
Changes:
- Added a new Quick Start Guide for building, configuring (SQLite), running, discovering, and viewing a topology.
- Added Tutorials for common workflows (MySQL setup, ProxySQL hooks, Prometheus, API v2).
- Added a long-form User Manual and an extensive Reference Manual covering config fields, CLI commands, and API v1/v2 endpoints.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| docs/quickstart.md | New “5-minute” getting-started guide with build + minimal config + discovery steps. |
| docs/tutorials.md | New step-by-step tutorials for setup, ProxySQL integration, Prometheus, and API v2 usage. |
| docs/user-manual.md | New multi-chapter manual spanning install/config through operations and troubleshooting. |
| docs/reference.md | New consolidated reference for configuration, CLI commands, and API endpoints. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "MySQLOrchestratorHost": "", | ||
| "MySQLOrchestratorPort": 0, | ||
| "MySQLOrchestratorDatabase": "", | ||
| "BackendDB": "sqlite", |
There was a problem hiding this comment.
In config examples, BackendDB is set to "sqlite", but the configuration struct documents the supported values as "mysql" or "sqlite3" (and error messages refer to sqlite3). To avoid confusing users (and to align with the reference/config.go), use "BackendDB": "sqlite3" in this example (and in any other SQLite examples in these new docs).
| "BackendDB": "sqlite", | |
| "BackendDB": "sqlite3", |
| { | ||
| "Debug": false, | ||
| "ListenAddress": ":3000", | ||
| "BackendDB": "sqlite", |
There was a problem hiding this comment.
This minimal config example uses "BackendDB": "sqlite", but the code/config comments describe supported values as "mysql" or "sqlite3". Please switch this example to "BackendDB": "sqlite3" to match go/config/config.go and the reference manual and to reduce confusion for users.
| "BackendDB": "sqlite", | |
| "BackendDB": "sqlite3", |
| ```json | ||
| { | ||
| "BackendDB": "sqlite", | ||
| "SQLite3DataFile": "/var/lib/orchestrator/orchestrator.db" | ||
| } |
There was a problem hiding this comment.
This SQLite backend example uses "BackendDB": "sqlite", while the code/config comments document the value as sqlite3. Please update the example to "BackendDB": "sqlite3" for consistency with go/config/config.go and docs/reference.md.
| To disable the continuous polling (for development/testing only): | ||
|
|
||
| ```bash | ||
| orchestrator --discovery=false http | ||
| ``` |
There was a problem hiding this comment.
--discovery=false disables the entire logic.ContinuousDiscovery() loop (instance polling, analysis/recovery ticks, etc.), not just continuous polling. As written, this can mislead readers into thinking only polling stops while other orchestrator behavior continues. Please clarify what actually stops (and what still works) when running http mode with --discovery=false.
| ```yaml | ||
| livenessProbe: | ||
| httpGet: | ||
| path: /api/status | ||
| port: 3000 | ||
| initialDelaySeconds: 10 | ||
| periodSeconds: 10 | ||
| readinessProbe: | ||
| httpGet: | ||
| path: /api/status | ||
| port: 3000 | ||
| initialDelaySeconds: 5 | ||
| periodSeconds: 5 | ||
| ``` |
There was a problem hiding this comment.
This section says to use the built-in Kubernetes health endpoints, but the probe examples use /api/status. /api/status runs a full process.HealthTest() (heavier, can fail on transient backend issues) and is not the lightweight liveness/readiness split provided by /health/live and /health/ready. Please update the examples to use /health/live for liveness and /health/ready for readiness (and optionally /health/leader where appropriate).
| All v2 responses use this structure: | ||
|
|
||
| ```json | ||
| { | ||
| "status": "ok", | ||
| "data": { ... }, | ||
| "message": "" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The v2 response envelope example shows a message field always present, but in V2APIResponse it is omitempty and respondOK does not set it. In practice, successful responses will typically be {status, data} without message. Please adjust the example to either omit message or explicitly note that it is optional and only present when set.
|
|
||
| Complete reference for orchestrator configuration, CLI commands, and HTTP API endpoints. | ||
|
|
||
| **Source of truth:** This document is generated from the orchestrator source code. Configuration fields come from the `Configuration` struct in `go/config/config.go`. CLI commands come from `go/app/cli.go`. API endpoints come from `go/http/api.go` and `go/http/apiv2.go`. |
There was a problem hiding this comment.
The header claims this reference is "generated from the orchestrator source code", but there doesn’t appear to be a generator script/check in the repo that ensures this file stays in sync. Unless there is an automated generation step being added elsewhere in this PR, please reword this to avoid implying an enforced source-of-truth relationship, or add a brief pointer to the generation process (script/command) so readers can reproduce it.
| **Source of truth:** This document is generated from the orchestrator source code. Configuration fields come from the `Configuration` struct in `go/config/config.go`. CLI commands come from `go/app/cli.go`. API endpoints come from `go/http/api.go` and `go/http/apiv2.go`. | |
| **Reference note:** This document is based on the orchestrator source code. Configuration fields correspond to the `Configuration` struct in `go/config/config.go`. CLI commands correspond to `go/app/cli.go`. API endpoints correspond to `go/http/api.go` and `go/http/apiv2.go`. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces significant updates and new content to the Orchestrator documentation, including quick start guides, a comprehensive reference manual, tutorials, and a user manual. The review comments highlight several areas for improvement, such as correcting the Go version requirement from a future release to a current stable one, adding explicit security warnings for example passwords used in tutorials, fixing a broken link to the full configuration guide, addressing a typo in a configuration key (Concensus), improving consistency in API v1 documentation regarding legacy slave terminology, updating Kubernetes health probe examples to use the new /health/live and /health/ready endpoints, and standardizing go build command syntax across the documentation.
|
|
||
| ## Prerequisites | ||
|
|
||
| - **Go 1.25+** (for building from source) |
There was a problem hiding this comment.
The required Go version is listed as 1.25+, which is a future version and not yet released. This is likely a typo. Please update it to a recent stable version, for example 1.22+.
| - **Go 1.25+** (for building from source) | |
| - **Go 1.22+** (for building from source) |
| CREATE USER 'orc_client_user'@'%' IDENTIFIED BY 'orc_client_password'; | ||
| GRANT SUPER, PROCESS, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'orc_client_user'@'%'; |
There was a problem hiding this comment.
The example user creation statement uses a weak, hardcoded password ('orc_client_password'). For security, it's important to advise users to replace this with a strong, generated password in any real environment. Please consider adding a note about this.
|
|
||
| ## Next steps | ||
|
|
||
| - [Full configuration guide](configuration.md) -- backend database options, discovery tuning, security, and more |
There was a problem hiding this comment.
The link to [Full configuration guide](configuration.md) appears to be broken as configuration.md is a table of contents. The new reference.md file contains the detailed configuration reference. Please update the link to point to the correct section in reference.md.
| - [Full configuration guide](configuration.md) -- backend database options, discovery tuning, security, and more | |
| - [Full configuration guide](reference.md#1-configuration-reference) -- backend database options, discovery tuning, security, and more |
| | `RaftDataDir` | string | `""` | Directory for raft data storage (required when `RaftEnabled` is true) | | ||
| | `DefaultRaftPort` | int | `10008` | Default port for `RaftNodes` entries that don't specify a port | | ||
| | `RaftNodes` | []string | `[]` | Raft nodes to make initial connection with | | ||
| | `ExpectFailureAnalysisConcensus` | bool | `true` | Expect failure analysis consensus before recovery | |
There was a problem hiding this comment.
The configuration key ExpectFailureAnalysisConcensus appears to have a typo (Concensus is misspelled). While this documentation correctly reflects the key from the source code, this could be confusing. It is recommended to fix this in the source code for better clarity and consistency, and then update the documentation.
|
|
||
| --- | ||
|
|
||
| ## 3. API v1 Reference |
There was a problem hiding this comment.
The CLI command reference includes a helpful "Command Synonyms" section that maps legacy terms like slave to replica. The API v1 reference also uses these legacy terms in many endpoints (e.g., /api/relocate-slaves/...) but lacks a similar explanatory note. For consistency and clarity, please consider adding a note to this section to inform users about the legacy terminology and its modern equivalent.
| ### What you will need | ||
|
|
||
| - A running MySQL master with one or more replicas (MySQL 5.7+ or 8.0+) | ||
| - Go 1.25+ installed |
There was a problem hiding this comment.
The required Go version is listed as 1.25+, which is a future version and not yet released. This is likely a typo. Please update it to a recent stable version, for example 1.22+.
| - Go 1.25+ installed | |
| - Go 1.22+ installed |
| CREATE USER 'orc_topology'@'orchestrator-host' IDENTIFIED BY 'a_secure_password'; | ||
| GRANT SUPER, PROCESS, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'orc_topology'@'orchestrator-host'; |
There was a problem hiding this comment.
This tutorial uses example passwords like 'a_secure_password'. While convenient for a tutorial, it's important to explicitly warn users against using these weak, hardcoded credentials in production environments. Please add a security note advising users to generate and use strong, unique passwords.
| livenessProbe: | ||
| httpGet: | ||
| path: /api/status | ||
| port: 3000 | ||
| initialDelaySeconds: 10 | ||
| periodSeconds: 10 | ||
| readinessProbe: | ||
| httpGet: | ||
| path: /api/status | ||
| port: 3000 | ||
| initialDelaySeconds: 5 | ||
| periodSeconds: 5 | ||
| ``` |
There was a problem hiding this comment.
This tutorial suggests using /api/status for Kubernetes liveness and readiness probes. However, the reference.md and user-manual.md documents introduce newer, more specific health endpoints: /health/live for liveness and /health/ready for readiness. To ensure users follow best practices, please update this example to use the new endpoints.
| livenessProbe: | |
| httpGet: | |
| path: /api/status | |
| port: 3000 | |
| initialDelaySeconds: 10 | |
| periodSeconds: 10 | |
| readinessProbe: | |
| httpGet: | |
| path: /api/status | |
| port: 3000 | |
| initialDelaySeconds: 5 | |
| periodSeconds: 5 | |
| ``` | |
| livenessProbe: | |
| httpGet: | |
| path: /health/live | |
| port: 3000 | |
| initialDelaySeconds: 10 | |
| periodSeconds: 10 | |
| readinessProbe: | |
| httpGet: | |
| path: /health/ready | |
| port: 3000 | |
| initialDelaySeconds: 5 | |
| periodSeconds: 5 |
| # Binary is output to bin/orchestrator | ||
|
|
||
| # Or build directly with go: | ||
| go build -o bin/orchestrator go/cmd/orchestrator/main.go |
There was a problem hiding this comment.
The go build command here is go build -o bin/orchestrator go/cmd/orchestrator/main.go. Other documentation files in this PR (like quickstart.md) use go build -o bin/orchestrator ./go/cmd/orchestrator. While both work, using the directory path is more common and idiomatic. For consistency across the documentation, please consider using the directory path form.
| go build -o bin/orchestrator go/cmd/orchestrator/main.go | |
| go build -o bin/orchestrator ./go/cmd/orchestrator |
| CREATE USER 'orchestrator'@'orc_host' IDENTIFIED BY 'orc_topology_password'; | ||
| GRANT SUPER, PROCESS, REPLICATION SLAVE, REPLICATION CLIENT, RELOAD ON *.* TO 'orchestrator'@'orc_host'; |
There was a problem hiding this comment.
This documentation uses an example password 'orc_topology_password'. While this is for documentation purposes, it's a security best practice to explicitly warn users not to use these examples in production. Please add a note advising the use of strong, generated passwords.
Comprehensive Documentation
3,144 lines of new documentation covering every aspect of orchestrator.
New documents
docs/quickstart.mddocs/tutorials.mddocs/user-manual.mddocs/reference.mdQuick Start Guide
Build → configure with SQLite → start → discover → view in web UI. Copy-paste ready.
Tutorials
User Manual (10 chapters)
Introduction, Installation, Discovery, Failure Detection, Recovery, ProxySQL Integration, Observability, High Availability, API Usage, Troubleshooting
Reference Manual
config.go)cli.go)api.go)Updated
docs/toc.md+docs/README.md— new "Getting Started" section at the topSummary by CodeRabbit