feat: Docker Compose one-click demo environment for Mega / Orion (#1792)

[WiedersehenM]

Summary

Related issue: #1792

This PR introduces a full Docker Compose stack that boots Mega, Orion, Campsite and all required infrastructure with a single command.
It streamlines local onboarding, showcases end-to-end functionality, and serves as a reproducible baseline for E2E tests or live demos.

---

Key Changes

• docker/demo/docker-compose.demo.yml:
  • Spins up PostgreSQL, MySQL, Redis, RustFS, Mega backend, Mega UI, Orion Server, Orion build client, and Campsite API.
  • Uses depends_on + healthcheck to guarantee deterministic startup.
• docker/demo/.env.example:
  • Centralises demo configuration (DB creds, S3 endpoint, ports).
• docker/demo/init-db.sh:
  • Creates mono and orion schemas on first Postgres start-up.
• docs/demo/docker-compose-guide-for-mega-and-orion-demo-setup.md:
  • Step-by-step guide covering prerequisites, commands, common issues, and demo workflow.
• orion-server/Dockerfile:
  • Translated comments to English; aligns BUILD_LOG_DIR with demo volume.
• orion-server/src/api.rs:
  • Merged upstream changes (prelude::DateTimeUtc) with local additions (QuerySelect) to resolve compile conflict.
• orion-server/src/server.rs:
  • Minor path update matching new log directory.

---

Motivation

1. Remove the friction of manually configuring multiple services for local development.
2. Provide a single, reproducible environment for contributors, CI, and demo purposes.

---

Usage

1. Prepare environment variables:
   cp docker/demo/.env.example docker/demo/.env
   2. Launch all services:
   docker compose -f docker/demo/docker-compose.demo.yml up -d
   3. Access Entry Points:
   • Mega UI: http://localhost:3000
   • Mega API: http://localhost:8000
   • Orion Server: http://localhost:8004/v2/health
   • RustFS console: http://localhost:9001

2. **Stop the stack:**h
   docker compose -f docker/demo/docker-compose.demo.yml down

Notes

• The stack is demo-only: no production-grade security hardening.
• Image priority: local tags > MEGA_*_IMAGE env vars > public ECR images.
• If port conflicts occur, adjust the host mappings in the compose file.

---

Checklist

• Signed-off-by and GPG signed (git commit -s -S)
• Passes GitHub Actions CI
• All comments are in English

[genedna]

@claude

[genedna]

@codex review

[github-actions]

Claude finished @genedna's task in 1m 44s —— View job

---

Code Review Complete

I've performed a comprehensive review of this Docker Compose demo environment PR. Overall, this is a well-structured implementation that successfully provides a one-click demo environment. Below are my findings organized by category.

---

Summary

Strengths:

• Well-organized Docker Compose configuration with proper dependency management
• Comprehensive documentation with troubleshooting guide
• Good use of health checks and deterministic startup ordering
• Clear separation of concerns between services

Areas for Improvement:

• Several security concerns (hardcoded credentials, privileged containers)
• Missing input validation in shell scripts
• Some configuration inconsistencies
• Documentation could be enhanced in a few areas

---

Detailed Findings

1. Security Issues

Critical:

1. Hardcoded Master Key in .env.example (docker/demo/.env.example:141)

   • The file contains CAMPSITE_RAILS_MASTER_KEY=wiedersehen which appears to be a real key
   • Recommendation: Replace with a placeholder value or empty string. The documentation already explains how to generate this key, so having a real value here is a security risk if accidentally committed.

2. Privileged Container (docker/demo/docker-compose.demo.yml:246)

   • The orion_build_client service runs with privileged: true
   • Recommendation: Document why this is necessary. If it's for Scorpio/containerization, consider using specific capabilities instead of full privileged mode:

     cap_add:
       - SYS_ADMIN
       - SYS_PTRACE

Important:

3. Default Passwords (Multiple files)

   • While the documentation warns this is demo-only, consider adding a startup warning that logs the insecure configuration
   • Recommendation: Add a banner message or startup script that warns users about default credentials

4. No Secret Scanning

   • No .gitignore entry for docker/demo/.env
   • Recommendation: Add docker/demo/.env to .gitignore to prevent accidental commits

---

2. Docker Compose Configuration

Good Practices Observed:

• ✅ Proper use of health checks
• ✅ Named volumes for data persistence
• ✅ Environment variable defaults with ${VAR:-default} syntax
• ✅ Custom network for service isolation

Issues:

1. Inconsistent Health Check Methods (docker/compose.demo.yml)

   • Some services use curl (orion_server:233, rustfs:90)
   • Others use bash /dev/tcp method (mega:161, mega_ui:196, campsite_api:318)
   • Recommendation: Be consistent. The bash method is clever for avoiding curl dependency, but document why different approaches are used.

2. RustFS Health Check May Fail (docker/demo/docker-compose.demo.yml:90)

   test: ["CMD-SHELL", "curl -f http://localhost:9000/health || exit 1"]

   • RustFS might not have a /health endpoint
   • Recommendation: Verify this endpoint exists, or use a simpler check like TCP connection test

3. MySQL Health Check Contains Password (docker/demo/docker-compose.demo.yml:61)

   test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -p${MYSQL_ROOT_PASSWORD:-mysqladmin} || exit 1"]

   • While functional, this exposes the password in process listings
   • Recommendation: MySQL 8.0 has better alternatives. Consider using a dedicated health check user without password

4. Campsite Migration Logic (docker/demo/docker-compose.demo.yml:305)

   if [ "$${CAMPSITE_RUN_MIGRATIONS:-1}" = "1" ]; then

   • Uses $$ to avoid Docker Compose variable substitution, but this is fragile
   • Recommendation: Document this clearly or use a different approach

5. Missing Resource Limits

   • No memory or CPU limits defined for any service
   • Recommendation: Add resource limits to prevent resource exhaustion:

     deploy:
       resources:
         limits:
           memory: 2G
         reservations:
           memory: 512M

---

3. Shell Script Issues

docker/demo/init-db.sh:

1. Script Does Nothing (init-db.sh:8-10)

   • The script only echoes messages and exits successfully
   • Recommendation: Either remove this script entirely or add actual initialization logic if needed in the future. The current version adds no value.

2. No Error Handling

   • Missing input validation
   • Recommendation: If keeping the script, add:

     set -euo pipefail

---

4. Configuration File Issues

.env.example:

1. Duplicate Key Definition (docker/demo/.env.example:137, 141)

   CAMPSITE_RAILS_MASTER_KEY=
   # ...
   CAMPSITE_RAILS_MASTER_KEY=wiedersehen

   • Key is defined twice
   • Recommendation: Remove one definition and use a placeholder value

2. Inconsistent Comment Style

   • Mix of detailed comments and minimal comments
   • Recommendation: Be consistent in commenting style

3. Missing Validation Notes

   • No notes about required formats (e.g., S3 bucket naming rules)
   • Recommendation: Add validation hints where applicable

---

5. Rust Code Changes

orion-server/Dockerfile:

• ✅ Good: English comments, multi-stage build, security conscious (strip binary)
• ✅ Good: Proper Cargo configuration for reliability

orion-server/src/api.rs:

• ✅ Code quality is good overall
• ✅ Proper use of imports and error handling
• No issues found related to this PR's changes

orion-server/src/server.rs:

• ✅ Clean implementation
• ✅ Good logging practices
• No issues found related to this PR's changes

---

6. Documentation Quality

docs/demo/docker-compose-guide-for-mega-and-orion-demo-setup.md:

Strengths:

• ✅ Comprehensive troubleshooting section
• ✅ Clear step-by-step instructions
• ✅ Good use of examples and code blocks
• ✅ Multiple warnings about production use

Issues:

1. Broken Internal Link (line 495)

   2. Check the service logs for troubleshooting.

   • Links to #常见问题-faq (Chinese characters in URL)
   • Recommendation: Fix to #frequently-asked-questions-faq

2. Inconsistent Language (Multiple locations)

   • Most content is in English, but some sections reference non-existent Chinese versions
   • Example line 487: References a Chinese architecture document that doesn't exist
   • Recommendation: Remove references to missing documents or create them

3. Time Estimates Present (line 130, 247)

   • "Typically you should wait 2–5 minutes"
   • "first startup usually takes 5–15 minutes"
   • Recommendation: While acceptable in documentation, consider rephrasing to be less specific: "typically takes a few minutes depending on your system"

4. Missing Information:

   • No mention of disk space requirements
   • No mention of system requirements (RAM, CPU)
   • Recommendation: Add a system requirements section

5. Image Pull Strategy Not Documented

   • Documentation doesn't explain the image priority (local > env var > ECR)
   • Recommendation: Add a section explaining image selection logic

---

7. Best Practices & Architecture

Positive:

• ✅ Good separation of concerns (infrastructure vs application services)
• ✅ Proper use of named volumes for persistence
• ✅ Health checks ensure reliable startup
• ✅ Clear naming conventions

Suggestions:

1. Add .dockerignore

   • No .dockerignore file present for the demo directory
   • Recommendation: Add .dockerignore to exclude unnecessary files from build context

2. Version Pinning

   • PostgreSQL: postgres:15 ✅ Good
   • Redis: redis:7 ✅ Good
   • MySQL: mysql:8.0 ✅ Good
   • Recommendation: Consider pinning to more specific versions for reproducibility

3. Network Security

   • All services expose ports to host
   • Recommendation: Document which ports are essential for external access vs. which could be internal-only

---

Testing Recommendations

Since I cannot run the actual stack, I recommend testing:

1. Startup Order: Verify all health checks pass and services start in correct order
2. Volume Persistence: Stop/start containers to verify data persists
3. Port Conflicts: Test with some ports already occupied
4. Resource Exhaustion: Test behavior under low memory conditions
5. Network Connectivity: Verify all service-to-service connections work
6. Log Rotation: Verify logs don't fill up disk space over time

---

Priority Recommendations

High Priority:

1. Remove or replace hardcoded CAMPSITE_RAILS_MASTER_KEY value
2. Add docker/demo/.env to .gitignore
3. Document why privileged: true is needed or remove it
4. Fix broken documentation link

Medium Priority:
5. Add resource limits to services
6. Make health checks consistent
7. Add system requirements to documentation
8. Remove or improve init-db.sh script

Low Priority:
9. Add .dockerignore file
10. Pin more specific image versions
11. Document image selection logic

---

Conclusion

This is a solid implementation of a Docker Compose demo environment. The core functionality is well-designed with proper dependency management and health checking. The main concerns are around security hardening (expected for a demo) and documentation completeness. Addressing the high-priority recommendations will significantly improve the security posture even for demo use.

The PR successfully achieves its goals of providing a one-click demo environment and serves as a good foundation for local development and testing.

Tasks

• Read and analyze all changed files
• Review Docker Compose configuration
• Review shell scripts and initialization logic
• Review Rust code changes
• Review documentation quality
• Check for security vulnerabilities
• Verify error handling and best practices
• Compile and post comprehensive review feedback

--- | Branch: feat/mega-orion-demo-compose

[Copilot]

Pull request overview

This PR introduces a comprehensive Docker Compose-based demo environment that orchestrates the entire Mega/Orion stack (Mega backend, Mega UI, Orion Server, Orion Build Client, and Campsite API) along with all required infrastructure services (PostgreSQL, MySQL, Redis, RustFS). The implementation aims to provide a one-click local development and demonstration setup with proper health checks and dependency management.

Changes:

• Added complete Docker Compose stack configuration with 8 services and proper health checks
• Implemented health check endpoint for Orion Server at /v2/health
• Enhanced Orion Server Dockerfile with improved build reliability and curl for health checks
• Created comprehensive documentation guide with troubleshooting and architecture overview

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
docker/demo/docker-compose.demo.yml	Main orchestration file defining 8 services with health checks, volume mounts, and environment configuration
docker/demo/.env.example	Template configuration file with database credentials, service URLs, and feature flags
docker/demo/init-db.sh	PostgreSQL initialization script (informational only, actual DB creation handled by POSTGRES_DB env var)
docs/demo/docker-compose-guide-for-mega-and-orion-demo-setup.md	Comprehensive 511-line guide covering prerequisites, setup, troubleshooting, and architecture
orion-server/Dockerfile	Enhanced with Cargo retry configuration, English comments, and curl installation for health checks
orion-server/src/api.rs	Added /v2/health endpoint with database connectivity check
orion-server/src/server.rs	Registered health check handler in API routes

[Copilot]

Typo in the command comment. The line reads "Stop the stack:h" with an extra "h" at the end. This should be removed for consistency with other section headers.

Suggested change

	### Stop services
	### Stop the stack

[Copilot]

Misleading comment about orion database creation. The comment states "orion will be created by init script" but the init-db.sh script does not create any orion database - it only prints informational messages. The comment should be updated to reflect that orion-server uses the same mono database, as correctly noted in line 21 of the init-db.sh script and elsewhere in the configuration.

Suggested change

	# Main DB is primarily used by mono; orion will be created by init script
	# Main DB is primarily used by mono; orion-server shares the same mono database

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a4eee9006a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Pass CAMPSITE_RUN_MIGRATIONS into container env

The entrypoint script checks CAMPSITE_RUN_MIGRATIONS, but the service environment never defines that variable (Compose only uses .env for interpolation unless you map it into environment or env_file). This means CAMPSITE_RUN_MIGRATIONS=0 in docker/demo/.env will never reach the container, so migrations always run on every start. If you want the documented toggle to work, add CAMPSITE_RUN_MIGRATIONS to the service environment or include an env_file.

Useful? React with 👍 / 👎.

[WiedersehenM]

正在根据review进行代码修改

[WiedersehenM]

Code Review Reply

已完成修复，以下逐条回应review建议并说明当前状态。

1 安全相关

• 硬编码 CAMPSITE_RAILS_MASTER_KEY
  已在 docker/demo/.env.example 删除真实值，改为空占位并去重。
  .gitignore 新增 docker/demo/.env，防止误提交真实密钥。

• privileged: true 风险
  在 orion_build_client 服务附近补充注释，解释其用于 Scorpio 内部构建。

• MySQL health-check 暴露密码
  当前命令保持 demo 可用性；文档新增显著提示：生产环境请创建低权限用户并调整 health-check，无需 root 密码。

2 Docker Compose 配置

Review 要求	处理结果
统一 health-check 写法	保持原状：因部分基础镜像不含 curl，且已在测试中全部通过，故暂无法统一；文档已说明原因。
CAMPSITE_RUN_MIGRATIONS 变量无法传入	已在 campsite_api.environment 显式添加同名变量，支持 .env 开关。
删除无用 init-db.sh	脚本已删除，同时移除 postgres 挂载行，避免启动失败。

3 Shell 脚本

• init-db.sh 无实际逻辑
  如上已彻底移除；数据库初始化完全依赖官方镜像变量，Compose 能正常启动。

4 代码修改

• Orion Server /v2/health 泄漏 DB 错误
  返回值改为固定 "database connectivity check failed"，仅在日志打印具体错误。

5 文档修复

• 修复 FAQ 锚点、Broken link；全角符号替换；删除中文残留。
• 新增硬件要求（4 CPU / 8 GB RAM）；说明镜像拉取优先级与 MySQL 安全建议。
• 新增端口说明、镜像选择策略与资源限制调优建议。

6 其他补充

• .dockerignore：排除 .git、target/、node_modules/ 等，减小 build context。
• Health-check 不统一：
  • 部分镜像（Redis、MySQL、bash-only镜像）缺 curl。
  • 统一为 bash /dev/tcp 会增加维护复杂度，且现有检查均已通过。
  • 未来若所有镜像均自行安装 curl，可再行统一。

未满足项与原因

1. 完全统一 health-check 命令
   如上所述，受基础镜像依赖限制暂不处理；现状已能保证稳定启动。

2. 全面资源限额
   考虑 demo 环境机器差异大，统一限额反而可能“误限”。