feat: add Complete Workflows for Standalone and Multi-CN Setup with Metrics

[XuPeng-SH]

User description

What type of PR is this?

• API-change
• BUG
• Improvement
• Documentation
• Feature
• Test and CI
• Code Refactoring

Which issue(s) this PR fixes:

issue #23246

What this PR does / why we need it:

Standalone MatrixOne

# Quick start
make build
./mo-service -launch ./etc/launch/launch.toml
mysql -h 127.0.0.1 -P 6001 -u root -p111

# With monitoring
make build
# Edit etc/launch/cn.toml, tn.toml, log.toml to enable metrics
./mo-service -launch ./etc/launch/launch.toml
make dev-up-grafana-local
make dev-check-grafana
make dev-create-dashboard-local

Multi-CN Cluster

# Quick start
make dev-build && make dev-up
mysql -h 127.0.0.1 -P 6001 -u root -p111

# With monitoring
make dev-build && make dev-up
make dev-edit-cn1  # Enable metrics in configs
make dev-restart
make dev-up-grafana
make dev-check-grafana
make dev-create-dashboard-cluster

---

PR Type

Enhancement, Documentation

---

Description

• Add comprehensive Grafana dashboard creation tool (mo-dashboard) with support for multiple deployment modes (local, cloud, K8S, cloud-ctrl)

• Implement complete development guide (DEV_README.md) covering standalone and multi-CN cluster setups with monitoring workflows

• Enhance Docker Compose setup with Prometheus and Grafana services, including cluster and local monitoring profiles

• Add Docker registry mirror configuration scripts for faster image pulls in regions with slow Docker Hub access

• Extend Makefile with 20+ new development commands for monitoring, dashboard creation, and service management

• Improve start.sh script with Grafana health checks, enhanced permission handling, and profile support

---

Diagram Walkthrough

flowchart LR
  A["mo-dashboard<br/>Command Tool"] -->|Creates| B["Grafana<br/>Dashboards"]
  C["Docker Compose<br/>Services"] -->|Includes| D["Prometheus<br/>Metrics"]
  D -->|Feeds| B
  E["DEV_README.md<br/>Documentation"] -->|Guides| F["Development<br/>Workflows"]
  G["Enhanced<br/>Makefile"] -->|Provides| H["20+ dev-*<br/>Commands"]
  H -->|Manages| C
  I["start.sh<br/>Script"] -->|Supports| J["Health Checks<br/>& Profiles"]

Loading

File Walkthrough

	Relevant files
Enhancement	8 files main.go New Grafana dashboard creation command tool                            +115/-0  main.go Integrate dashboard command into mo-tool CLI                          +4/-1      start.sh Enhanced script with Grafana checks and profiles                  +225/-23 setup-docker-mirror.sh New Docker registry mirror configuration script                    +78/-0    update-docker-mirror.sh Docker mirror update utility for better reliability            +72/-0    Makefile Add 20+ dev-* commands for monitoring and dashboards          +236/-5  docker-compose.yml Add Prometheus and Grafana services with profiles                +181/-3  Dockerfile.dev Development Dockerfile with cached dependencies                    +61/-0
Documentation	4 files DEV_README.md Comprehensive development guide with all workflows              +1532/-0 README_CN.md Add Chinese documentation for development setup                    +18/-0    README_USER.md Link to development guide for Python SDK users                      +10/-0    README.md Update main README with development guide link                      +1/-1
Configuration changes	8 files prometheus-local.yml Prometheus config for monitoring local MatrixOne                  +76/-0    prometheus.yml Prometheus config for Docker Compose cluster                          +53/-0    default.yml Grafana dashboard provisioning configuration                          +13/-0    prometheus-cluster.yml Grafana data source config for cluster Prometheus                +11/-0    cn.toml Enable metrics in standalone CN configuration                        +4/-0      prometheus.yml Grafana data source config for local Prometheus                    +11/-0    log.toml Enable metrics in standalone Log service config                    +6/-1      tn.toml Enable metrics in standalone TN configuration                        +5/-0
Additional files	1 files README.md +0/-829

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Weak default credentials Description: The CLI exposes default Grafana credentials (--username admin, --password admin) which, if used against a reachable/non-local Grafana, can enable unauthorized dashboard modifications; ensure non-default secrets for non-local deployments or require explicit credentials. main.go [107-112] Referred Code cmd.Flags().StringVar(&host, "host", "127.0.0.1", "Grafana host address") cmd.Flags().IntVar(&port, "port", 3001, "Grafana port (default: 3001 for local, 3000 for docker compose)") cmd.Flags().StringVar(&mode, "mode", "local", "Dashboard mode: local, cloud, k8s, cloud-ctrl (default: local)") cmd.Flags().StringVar(&username, "username", "admin", "Grafana username (default: admin)") cmd.Flags().StringVar(&password, "password", "admin", "Grafana password (default: admin)") cmd.Flags().StringVar(&datasource, "datasource", "Prometheus", "Prometheus datasource name (for cloud/k8s modes, default: Prometheus)")
	Untrusted mirror configuration Description: The script, intended to run as root, rewrites /etc/docker/daemon.json with a curated list of third-party registry mirrors and restarts Docker without validating sources or preserving prior settings, which can be abused in supply-chain attacks if mirrors are malicious or the script is tampered with. setup-docker-mirror.sh [58-66] Referred Code # Restart Docker daemon echo "Restarting Docker daemon..." if systemctl is-active --quiet docker; then systemctl restart docker # edev-up-prometheus-localcho "✅ Docker daemon restarted" else echo "⚠️ Docker daemon is not running. Please start it manually:" echo " sudo systemctl start docker" fi
	Risky sudo chown recursion Description: The ownership-fix flow may invoke sudo chown -R "$DOCKER_UID:$DOCKER_GID" "$dir" on developer-specified or environment-influenced paths (e.g., EXTRA_MOUNTS) which could lead to privilege misuse or unintended recursive ownership changes if variables are manipulated. start.sh [331-349] Referred Code if chown -R "$DOCKER_UID:$DOCKER_GID" "$dir" 2>/dev/null; then echo " ✓ Ownership fixed (no sudo required)" elif sudo -n chown -R "$DOCKER_UID:$DOCKER_GID" "$dir" 2>/dev/null; then echo " ✓ Ownership fixed (no password required)" else # If sudo -n fails, check if user wants to skip if [ "$SKIP_SUDO" = false ]; then echo " ⚠ Files in $dir were previously created by Docker as root" echo " To fix ownership, sudo is required (you'll be prompted for password)" echo " If you prefer to skip this, set SKIP_SUDO_FIX=true and fix manually later" if sudo chown -R "$DOCKER_UID:$DOCKER_GID" "$dir" 2>/dev/null; then echo " ✓ Ownership fixed" else echo " ⚠ Could not fix ownership for $dir" echo " You can manually fix it later with:" echo " sudo chown -R $DOCKER_UID:$DOCKER_GID $dir" echo " Or skip this check by setting: SKIP_SUDO_FIX=true" SKIP_SUDO=true fi
	Privileged script execution Description: The dev-setup-docker-mirror target enforces execution as root and then runs ./setup-docker-mirror.sh from a relative path, which could be replaced or modified to execute arbitrary code with root privileges if the working directory is compromised. Makefile [642-647] Referred Code @if [ "$$(id -u)" -ne 0 ]; then \ echo "This command needs to be run with sudo:"; \ echo " sudo make dev-setup-docker-mirror"; \ exit 1; \ fi @bash -c 'cd $(DEV_DIR) && ./setup-docker-mirror.sh'
	Metrics endpoint exposure Description: Prometheus is configured to scrape host.docker.internal:7001; if local MatrixOne metrics are exposed without authentication, sensitive operational metrics become accessible to any process/container on the host, risking information disclosure. prometheus-local.yml [36-43] Referred Code - job_name: 'mo-cn-local' static_configs: - targets: ['host.docker.internal:7001'] # Default status port, adjust if needed labels: service: 'cn' instance: 'mo-cn-local' deployment: 'local'
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Action Logging: The new CLI operations that create dashboards and interact with Grafana are not accompanied by audit logging of who performed the action and its outcome beyond console prints, which may not satisfy audit trail requirements depending on runtime context. Referred Code RunE: func(cmd *cobra.Command, args []string) error { grafanaURL := fmt.Sprintf("http://%s:%d", host, port) var creator *dashboard.DashboardCreator switch mode { case "local": creator = dashboard.NewLocalDashboardCreator( grafanaURL, username, password, "Matrixone-Standalone", ) fmt.Printf("Creating local dashboard at %s (folder: Matrixone-Standalone)\n", grafanaURL) case "cloud": creator = dashboard.NewCloudDashboardCreator( grafanaURL, username, password, datasource, ... (clipped 34 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Error Handling: The shell script prints guidance but often continues after failures (e.g., ownership fixes, port checks) and relies on external tools without validating their presence comprehensively, which may lead to silent or partial failures. Referred Code check_port() { local port=$1 local name=$2 local url=$3 # Check if port is listening if command -v nc >/dev/null 2>&1; then if ! nc -z localhost "$port" 2>/dev/null; then echo " ✗ $name (port $port): Not listening" return 1 fi elif command -v ss >/dev/null 2>&1; then if ! ss -lnt | grep -q ":$port "; then echo " ✗ $name (port $port): Not listening" return 1 fi fi # Try to connect via HTTP/HTTPS if [ -n "$url" ]; then if command -v curl >/dev/null 2>&1; then ... (clipped 80 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Credential Echo: The CLI accepts Grafana credentials via flags and may log operation details to stdout; while the code does not print the password, using command-line flags can expose credentials in shell history or process lists, which may violate secure logging/handling practices. Referred Code cmd.Flags().StringVar(&host, "host", "127.0.0.1", "Grafana host address") cmd.Flags().IntVar(&port, "port", 3001, "Grafana port (default: 3001 for local, 3000 for docker compose)") cmd.Flags().StringVar(&mode, "mode", "local", "Dashboard mode: local, cloud, k8s, cloud-ctrl (default: local)") cmd.Flags().StringVar(&username, "username", "admin", "Grafana username (default: admin)") cmd.Flags().StringVar(&password, "password", "admin", "Grafana password (default: admin)") cmd.Flags().StringVar(&datasource, "datasource", "Prometheus", "Prometheus datasource name (for cloud/k8s modes, default: Prometheus)") Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Input Validation: User-supplied flags like host, port, mode, and datasource are minimally validated (only mode is checked), which could allow invalid endpoints or misconfiguration when connecting to Grafana without additional sanitization. Referred Code cmd.Flags().StringVar(&host, "host", "127.0.0.1", "Grafana host address") cmd.Flags().IntVar(&port, "port", 3001, "Grafana port (default: 3001 for local, 3000 for docker compose)") cmd.Flags().StringVar(&mode, "mode", "local", "Dashboard mode: local, cloud, k8s, cloud-ctrl (default: local)") cmd.Flags().StringVar(&username, "username", "admin", "Grafana username (default: admin)") cmd.Flags().StringVar(&password, "password", "admin", "Grafana password (default: admin)") cmd.Flags().StringVar(&datasource, "datasource", "Prometheus", "Prometheus datasource name (for cloud/k8s modes, default: Prometheus)") Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix incorrect docker compose arguments Fix a bug in the start.sh script where arguments to docker compose up were being duplicated. The fix prepends the --profile argument to the command array, ensuring correct command construction. etc/docker-multi-cn-local-disk/start.sh [384-396] # Add --profile matrixone if up command is used and no profile is specified -# Profile must be before the 'up' command, not after if [[ " ${DOCKER_COMPOSE_ARGS[*]} " =~ " up " ]] && [[ ! " ${DOCKER_COMPOSE_ARGS[*]} " =~ " --profile " ]]; then - # Find the position of 'up' and insert --profile matrixone before it - NEW_ARGS=() - for arg in "${DOCKER_COMPOSE_ARGS[@]}"; do - if [ "$arg" = "up" ]; then - NEW_ARGS+=("--profile" "matrixone") - fi - NEW_ARGS+=("$arg") - done - DOCKER_COMPOSE_ARGS=("${NEW_ARGS[@]}") + DOCKER_COMPOSE_ARGS=("--profile" "matrixone" "${DOCKER_COMPOSE_ARGS[@]}") fi Apply / Chat Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a bug in how docker compose arguments are constructed, which would lead to incorrect commands like up -d becoming ... up -d up -d. The proposed fix is correct and robust, preventing command execution failures.	Medium
High-level	Consolidate complex shell logic into scripts Extract complex shell logic for permission handling and service checks from the Makefile and start.sh into separate, dedicated helper scripts to improve readability and maintainability. Examples: etc/docker-multi-cn-local-disk/start.sh [277-369] # Pre-create directories with correct permissions (before docker creates them as root) if [[ " ${DOCKER_COMPOSE_ARGS[*]} " =~ " up " ]]; then echo "Pre-creating directories with correct permissions..." DATA_DIRS=("../../mo-data" "../../logs" "../../prometheus-data" "../../prometheus-local-data" "../../grafana-data" "../../grafana-local-data") # Create directories and set ownership immediately to prevent root ownership for dir in "${DATA_DIRS[@]}"; do mkdir -p "$dir" # Try to set ownership immediately (may fail if dir exists and is root-owned, but that's OK) chown "$DOCKER_UID:$DOCKER_GID" "$dir" 2>/dev/null || true ... (clipped 83 lines) Makefile [472-542] dev-up-grafana-local: @echo "Starting Grafana dashboard for local MatrixOne services..." @echo "" @echo "Note: This will pull prom/prometheus:latest from Docker Hub." @echo "If pull fails due to timeout, configure Docker mirror first:" @echo " cd $(DEV_DIR) && sudo ./setup-docker-mirror.sh" @echo " Or: sudo make dev-setup-docker-mirror" @echo "" @echo "Pre-creating directories with correct permissions..." @mkdir -p prometheus-local-data grafana-local-data grafana-local-data/dashboards && \ ... (clipped 61 lines) Solution Walkthrough: Before: # In etc/docker-multi-cn-local-disk/start.sh if [[ " ${DOCKER_COMPOSE_ARGS[*]} " =~ " up " ]]; then echo "Pre-creating directories with correct permissions..." DATA_DIRS=("../../mo-data" "../../logs" ...) # ... many lines of complex logic ... for dir in "${DATA_DIRS[@]}"; do if [ -d "$dir" ]; then # ... check for root-owned files using find ... if find "$dir" -user root | head -1 | grep -q .; then echo "Fixing ownership for $dir..." # ... try chown, then sudo -n chown, then sudo chown ... fi fi done fi docker compose ... After: # In etc/docker-multi-cn-local-disk/start.sh if [[ " ${DOCKER_COMPOSE_ARGS[*]} " =~ " up " ]]; then # Delegate complex logic to a dedicated script ./scripts/prepare-dev-environment.sh fi docker compose ... # New file: etc/docker-multi-cn-local-disk/scripts/prepare-dev-environment.sh #!/bin/bash echo "Pre-creating directories and fixing permissions..." DATA_DIRS=("../../mo-data" "../../logs" ...) DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) for dir in "${DATA_DIRS[@]}"; do # ... complex logic to check and fix ownership ... done echo "Environment ready." Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that the PR introduces complex shell logic directly into Makefile and start.sh, which harms maintainability; extracting this logic into dedicated scripts is a valid and significant architectural improvement.	Medium
General	Remove duplicate help message entries Remove duplicate help message entries for dev-check-grafana and dev-setup-docker-mirror from the dev-help target in the Makefile to clean up the output. Makefile [347-364] @echo " make dev-logs-proxy - Show proxy logs" + @echo " make dev-logs-grafana - Show Grafana logs" + @echo " make dev-logs-grafana-local - Show local Grafana logs" -+ @echo " make dev-check-grafana - Check if Grafana services are ready (ports 3000, 3001)" @echo " make dev-clean - Stop and remove all data (WARNING: destructive!)" + @echo " make dev-cleanup - Interactive cleanup (stops containers, removes data directories)" @echo " make dev-config - Generate config from config.env" ... @echo " make dev-edit-tn - Edit TN configuration interactively" @echo " make dev-edit-common - Edit common configuration (all services)" -+ @echo " make dev-setup-docker-mirror - Configure Docker registry mirror (for faster pulls)" + @echo "" + @echo "Dashboard Creation (via mo-tool):" [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies and proposes to remove duplicate help messages for dev-check-grafana and dev-setup-docker-mirror that were introduced in the PR, which improves the clarity of the make dev-help output.	Low
Update