Restructure and improve self-hosted documentation

[wubx]

Background

The current self-hosted documentation has grown organically and has several structural and content gaps that make it harder for users to find what they need.

Proposed Structure

self-hosted/
├── editions/                    # Edition overview and licensing
├── quickstart/                  # Quick start guide
├── deployment/                  # Deployment
│   ├── overview                 # Architecture overview and deployment options
│   ├── requirements             # Hardware and software requirements
│   ├── docker/                  # Docker deployment (recommended for getting started)
│   │   ├── deploying-local      # Docker Compose
│   │   └── deploying-offline    # Air-gapped environments
│   ├── kubernetes/              # Kubernetes deployment
│   ├── benddeploy/              # BendDeploy (recommended for production)
│   └── object-storage/          # Object storage configuration
│       ├── overview
│       ├── amazon-s3
│       ├── google-gcs
│       ├── azure-blob
│       ├── minio
│       ├── other                # Wasabi, CubeFS, R2, OSS, COS, etc.
│       └── preparing-storage
│
├── databend-meta/               # Meta Service
│   ├── deploy                   # Deploy a Meta cluster
│   ├── node-manage              # Add and remove nodes
│   ├── backup-restore           # Backup and restore
│   └── status-and-monitoring    # Status and monitoring (merged from status + grpc)
│
├── databend-query/              # Query Service
│   ├── deploy                   # Deploy Query nodes
│   ├── cluster                  # Query cluster management
│   ├── scale                    # Scaling
│   └── status-and-monitoring    # Status and monitoring
│
├── operations/                  # Operations
│   ├── monitoring/              # Metrics monitoring (Prometheus/Grafana)
│   ├── logging/                 # Logging (new dedicated section)
│   │   ├── server-logs          # Server log configuration and retrieval
│   │   └── tracing              # Distributed tracing (Jaeger)
│   ├── upgrade/                 # Upgrade procedures
│   ├── backup-restore/          # Data backup and restore
│   ├── security/                # Security hardening (new)
│   └── troubleshooting/         # Troubleshooting (new)
│
└── references/                  # Reference
    ├── node-config/             # Node configuration parameters
    │   ├── metasrv-config       # Meta service configuration
    │   ├── query-config         # Query service configuration
    │   └── environment-variables
    ├── admin-users
    └── warehouse-sql-commands

Design Principles

• databend-meta/ and databend-query/ contain operational content only (deploy, manage, monitor)
• Configuration parameters are consolidated under references/node-config/
• deployment/ focuses on how to install, component management belongs in their own sections
• operations/ covers cross-component operations (monitoring, logging, upgrade, security, troubleshooting)
• logging/ is a dedicated section separate from monitoring/ — they serve different purposes

Content Mapping (Current → New)

Current	New Location
02-deployment/01-deploying-local.md	deployment/docker/deploying-local
02-deployment/02-deploying-offline.md	deployment/docker/deploying-offline
02-deployment/03-deploying-databend.md	Split: storage config → deployment/object-storage/, deploy steps → databend-meta/deploy + databend-query/deploy
02-deployment/05-understanding-deployment-modes.md	deployment/overview
02-production/01-preparing-storage.md	deployment/object-storage/preparing-storage
02-production/02-deploying-databend-on-kubernetes.md	deployment/kubernetes/
02-production/03-manage-query-warehouse-through-SQL.md	databend-query/cluster
02-production/10-metasrv-deploy.md	databend-meta/deploy
02-production/16-metasrv-grpc.md	databend-meta/status-and-monitoring
02-production/20-metasrv-add-remove-node.md	databend-meta/node-manage
02-production/30-metasrv-backup-restore.md	databend-meta/backup-restore
02-production/60-metasrv-status.md	databend-meta/status-and-monitoring
02-production/70-metasrv-cli-api.md	references/node-config/ (CLI reference)
02-production/90-benddeploy/	deployment/benddeploy/
03-operations/monitoring/20-server-logs.md	operations/logging/server-logs
03-operations/monitoring/30-tracing.md	operations/logging/tracing
03-operations/monitoring/ (metrics only)	operations/monitoring/
03-operations/upgrade/	operations/upgrade/
04-references/node-config/	references/node-config/
04-references/admin-users	references/admin-users
04-references/warehouse-sql-commands	references/warehouse-sql-commands

Missing Content to Add

1. deployment/requirements — Hardware/software requirements and environment checklist
2. deployment/overview — Architecture overview and deployment option comparison
3. databend-query/deploy — Query node deployment (currently only mentioned inside the meta deploy doc)
4. databend-query/scale — Query node scaling
5. databend-query/status-and-monitoring — Query node status and monitoring
6. operations/backup-restore — Data-level backup and restore strategy
7. operations/security — TLS configuration, network isolation, authentication best practices
8. operations/troubleshooting — Common errors, log analysis, diagnostic steps

Implementation Plan

• Step 1: Extract databend-meta section — Move metasrv pages from 02-production/ to top-level databend-meta/, merge status + grpc into one page, update all redirects and links
• Step 2: Create databend-query section — Move manage-query-warehouse-through-SQL to databend-query/cluster, create stub pages for deploy/scale/status-and-monitoring
• Step 3: Reorganize deployment/ — Move docker pages into docker/ subdir, promote benddeploy/, create object-storage/ section, split 03-deploying-databend.md

Related

• Improve production deployment docs: recommend BendDeploy as the primary self-hosted production path #3138 — Recommend BendDeploy as primary production path
• Remove or clarify the 'Download' page under Self-hosted deployment #3137 — Remove download page (done in docs: improve self-hosted deployment docs structure #3139)