⚠️ Important Notice: This Docker Compose setup is for local demo/development only. Do NOT run it in production. Default passwords and test users are included.

• Prerequisites
• Quick Start
• Demo Walk-Through
• Service Endpoints
• FAQ
• Stopping and Cleanup
• View logs
• Architecture Overview

This demo ships multi-architecture Docker images (linux/amd64 + linux/arm64). If you are on an Apple Silicon machine:

1. Ensure you are running Docker Desktop ≥ 4.22 (includes Compose v2 and built-in Rosetta/QEMU).
2. Simply follow the normal steps—Docker will automatically pull the arm64 layers from the public registry.
3. If the arm64 variant is not yet available (e.g. you are on a fresh fork), trigger the GitHub workflow “Demo multi-arch images”: Actions → Demo multi-arch images → Run workflow.
4. As a fall-back you can force emulation by adding --platform linux/amd64 after every docker compose command, but native arm64 images are strongly recommended.

• Linux – native Docker & Compose
• macOS – Docker Desktop
• Windows – Docker Desktop (WSL2 recommended)

Hardware (minimum):

• CPU: 4 cores
• RAM: 8 GB (16 GB recommended for source builds)
• Disk: 10 GB free (30 GB recommended if building images locally)

• Docker ≥ 20.10
• Docker Compose ≥ 2 (bundled with Docker Desktop)

docker --version
docker compose version

git clone https://github.com/web3infra-foundation/mega.git
cd mega

Hosts mapping (required for demo domains)

The demo uses virtual domains under gitmono.local. Add the following line to your operating-system hosts file so that the browser resolves them to your local machine:

127.0.0.1 app.gitmono.local git.gitmono.local api.gitmono.local auth.gitmono.local orion.gitmono.local

On Linux/macOS this is /etc/hosts; on Windows it is C:\Windows\System32\drivers\etc\hosts. You can remove the mapping at any time after testing.

The demo environment already has sensible default values and can be used as-is. To customize any settings, create a .env file under docker/demo/:

cd docker/demo
# (Optional) copy `.env.example` to `.env` and edit as needed

The main configurable environment variables include:

• Database Configuration:

  • POSTGRES_USER: PostgreSQL username (default: postgres)
  • POSTGRES_PASSWORD: PostgreSQL password (default: postgres)
  • POSTGRES_DB_MONO: PostgreSQL database name (default: mono, shared by Mega + Orion Server)
  • MYSQL_ROOT_PASSWORD: MySQL root password (default: mysqladmin)
    • ⚠️ For production, create a dedicated low-privilege user and update the MySQL health-check accordingly (avoid embedding root password).
  • MYSQL_DATABASE: Campsite database name (default: campsite, uses MySQL)

• Service Images:

  • MEGA_ENGINE_IMAGE: Mega backend image (default: public.ecr.aws/m8q5m4u3/mega/mono-engine:latest)
  • MEGA_UI_IMAGE: Mega UI unified image (default: public.ecr.aws/m8q5m4u3/mega/mega-ui:latest)
  • CAMPSITE_API_IMAGE: Campsite API image (default: public.ecr.aws/m8q5m4u3/mega/campsite-api:latest)
  • CAMPSITE_HOST_PORT: Host port for Campsite API (default: 18080, maps to container port 8080; avoids conflict with local tools such as Cursor on 8080)
  • CAMPSITE_RUN_MIGRATIONS: Whether to run database migrations when the container starts; 1 (default) to run, can be changed to 0 after the first successful migration to skip and speed up subsequent starts.

• Mega UI Runtime URLs (injected at container start; must be browser-reachable):

  • NEXT_PUBLIC_API_URL: Campsite API for the browser (default: http://api.gitmono.local:18080)
  • NEXT_PUBLIC_INTERNAL_API_URL: Campsite API for Next.js SSR inside the mega_ui container (default: http://api.gitmono.local:8080 — Docker network alias + container port 8080, not host port 18080)
  • NEXT_PUBLIC_MONO_API_URL: Mega / mono API (default: http://git.gitmono.local:8000)
  • NEXT_PUBLIC_ORION_API_URL: Orion Server API (default: http://orion.gitmono.local:8004)
  • NEXT_PUBLIC_AUTH_URL: OAuth / auth endpoint (default: http://auth.gitmono.local:18080)
  • NEXT_PUBLIC_WEB_URL: Web UI origin (default: http://app.gitmono.local)
  • NEXT_PUBLIC_SYNC_URL: Real-time sync WebSocket URL (optional; leave empty if not used)
  • NEXT_PUBLIC_CRATES_PRO_URL: Crates Pro API URL (optional; leave empty if not used)

  The UI image is environment-agnostic: it is built once with placeholder URLs and docker-entrypoint.sh rewrites them from the variables above when mega_ui starts. You no longer need per-environment image tags such as demo-latest.

• RustFS Configuration:

  • RUSTFS_ACCESS_KEY: RustFS access key (default: rustfsadmin)
  • RUSTFS_SECRET_KEY: RustFS secret key (default: rustfsadmin)

• Mega Backend Configuration:

  • MEGA_MONOREPO__ADMIN: Add your GitHub login name here to grant admin access (comma-separated for multiple users)(default: Null)

Note: The demo environment uses default passwords and test users for demonstration purposes only.

Execute in the project root directory:

docker compose -f docker/demo/docker-compose.demo.yml up -d

Or, if you maintain a local .env under docker/demo/:

cd docker/demo
docker compose -f docker-compose.demo.yml up -d

This command will:

1. Pull the required Docker images (may take a long time for the first run)
2. Create Docker networks and volumes
3. Start all services in dependency order:
   • First, start infrastructure services (PostgreSQL, MySQL, Redis, RustFS)
   • Then, start application services (Mega, Orion Server, Campsite API)
   • Finally, start mega_ui, which injects NEXT_PUBLIC_* URLs at container start and serves the web UI on port 80

On first mega_ui start you should see log lines such as [entrypoint] injecting runtime environment followed by NEXT_PUBLIC_* applied — that confirms the unified image picked up your demo URLs.

View the status of all services:

docker compose -f docker/demo/docker-compose.demo.yml ps

View service logs (follow):

docker compose -f docker/demo/docker-compose.demo.yml logs -f

View logs for specific services:

docker compose -f docker/demo/docker-compose.demo.yml logs -f mega
docker compose -f docker/demo/docker-compose.demo.yml logs -f orion_server

On the first startup, services may take some time to finish:

• Database initialization: PostgreSQL and MySQL need to initialize the databases
• Service health checks: Each service waits for its dependencies to become healthy before starting
• Image build: If using locally built images, the mega and orion_server services need to be built from source (slower on the first run)
• PostgreSQL init script: On the very first launch the container runs docker/demo/init-db.sh automatically (mounted into /docker-entrypoint-initdb.d/). The script does not create extra schemas; it simply prints helpful hints and reminds you that the mono database is auto-created by the POSTGRES_DB variable. Because the PostgreSQL data directory is persisted in the postgres-data volume, this script is executed only once unless you delete the volume.

Typically you should wait 2–5 minutes. You can monitor service health with the following command:

# View the health status of all services
docker compose -f docker/demo/docker-compose.demo.yml ps

When all services show a status of healthy or running, you can start using the demo.

Open your browser and visit:

http://app.gitmono.local

The demo environment includes a built-in test user you can use directly:

• Username: mega
• Token: mega

In Mega UI:

1. Create a new monorepo project or select an existing one
2. On the project page, find the build-related features
3. Trigger a Buck2 build task
4. The build request will be sent to Orion Server and executed by Orion Build Client

• View in the UI: Build status and logs are displayed in Mega UI

• View build client logs:

  docker compose -f docker/demo/docker-compose.demo.yml logs -f orion_build_client

• View Orion Server logs:

  docker compose -f docker/demo/docker-compose.demo.yml logs -f orion_server

RustFS object storage provides a web console:

http://localhost:9001/rustfs/console/access-keys

Log in with the following credentials:

• Access Key: rustfsadmin (or the value of RUSTFS_ACCESS_KEY)
• Secret Key: rustfsadmin (or the value of RUSTFS_SECRET_KEY)

• Mega API: GET http://api.gitmono.local:8000/api/v1/status
• Orion Server: GET http://orion.gitmono.local:8004/v2/health
• Campsite API: GET http://api.gitmono.local:18080/health

Problem: After opening http://app.gitmono.local, API calls fail or target placeholder hostnames such as rt-api.placeholder.local.

Cause: The unified UI image did not receive NEXT_PUBLIC_* values at container start (older image without docker-entrypoint.sh, or missing environment block).

Solution:

1. Ensure mega_ui uses public.ecr.aws/m8q5m4u3/mega/mega-ui:latest (or a locally built unified image).

2. Confirm docker/demo/.env includes the NEXT_PUBLIC_* block from .env.example, or rely on the defaults in docker-compose.demo.yml.

3. Restart the UI container and check logs:

   docker compose -f docker/demo/docker-compose.demo.yml logs mega_ui | grep entrypoint

   You should see NEXT_PUBLIC_* applied for each configured variable.

Issue: Docker reports the port is already allocated

Solution:

1. Update the port mapping in the compose file: Edit docker/demo/docker-compose.demo.yml and adjust the ports section, e.g.:

   ports:
     - "8001:8000"  # Change host port to 8001

2. Stop the service occupying the port:

   # Find the process occupying the port (Linux/macOS)
   lsof -i :8000
   # or use netstat (Windows)
   netstat -ano | findstr :8000

Issue: First run of docker compose up takes a long time

Reason:

• Images must be pulled from remote registries (may be large)
• If you are using locally built images, the mega and orion_server services need to be built from source
• PostgreSQL and MySQL databases need to initialize

Solution:

• Be patient; the first startup usually takes 5–15 minutes (depending on network speed and hardware)
• You can view progress in real time with docker compose logs -f
• Subsequent starts will be much faster (images are cached)

Issue: Some services remain in unhealthy or restarting state

Troubleshooting Steps:

1. View service logs:

   docker compose -f docker/demo/docker-compose.demo.yml logs <service_name>

2. Check dependency services: Ensure infrastructure services (PostgreSQL, MySQL, Redis, RustFS) are healthy:

   docker compose -f docker/demo/docker-compose.demo.yml ps

3. Check environment variables: Verify the .env file (if present) has correct settings

4. Check network connectivity: Ensure container-to-container network communication is normal:

   docker network inspect mega-demo-network

5. Restart a service:

   docker compose -f docker/demo/docker-compose.demo.yml restart <service_name>

Problem: The orion_build_client container cannot connect to orion_server.

Possible causes:

• orion_server has not fully started yet
• Incorrect WebSocket address configuration
• Network issues

Solution:

1. Check whether orion_server is healthy:

   docker compose -f docker/demo/docker-compose.demo.yml ps orion_server

2. Inspect orion_build_client logs:

   docker compose -f docker/demo/docker-compose.demo.yml logs orion_build_client

3. Verify that the backend is pointing at the correct Orion server URL (default: http://orion_server:8004) via MEGA_BUILD__ORION_SERVER.

Problem: Mega, Orion, or Campsite cannot connect to the database.

Troubleshooting steps:

1. Check whether PostgreSQL is healthy (used by Mega and Orion):

   docker compose -f docker/demo/docker-compose.demo.yml ps postgres

2. Check whether MySQL is healthy (used by the Campsite API):

   docker compose -f docker/demo/docker-compose.demo.yml ps mysql

3. Check database connection strings:

   • Mega/Orion: ensure DATABASE_URL or MEGA_DATABASE__DB_URL is correctly formatted (PostgreSQL)
   • Campsite: ensure CAMPSITE_DATABASE_URL is correctly formatted (MySQL; format: mysql2://user:password@host:port/database)

4. Test connectivity manually:

   # Test PostgreSQL connection (Mega/Orion)
   docker compose -f docker/demo/docker-compose.demo.yml exec postgres psql -U postgres -d mono
   
   # Test MySQL connection (Campsite)
   docker compose -f docker/demo/docker-compose.demo.yml exec mysql mysql -u root -p${MYSQL_ROOT_PASSWORD:-mysqladmin} -e "USE campsite; SELECT 1;"

Problem: Mega or Orion cannot access RustFS object storage.

Troubleshooting steps:

1. Check whether RustFS is healthy:

   docker compose -f docker/demo/docker-compose.demo.yml ps rustfs

2. Check S3 configuration: Ensure MEGA_S3__ENDPOINT_URL points to http://rustfs:9000 (in-container address).

3. Check access keys: Ensure S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY match the RustFS configuration.

Problem: orion_server failed to build.

Possible causes:

• Docker build context issues
• Network issues (unable to download dependencies)
• Insufficient disk space

Solution:

1. View detailed build logs:

   docker compose -f docker/demo/docker-compose.demo.yml build --no-cache orion_server

2. Check disk space:

   df -h  # Linux/macOS

3. Prune Docker cache:

   docker system prune -a

Stop all services (keep data):

docker compose -f docker/demo/docker-compose.demo.yml stop

Stop and remove containers (keep volumes):

docker compose -f docker/demo/docker-compose.demo.yml down

⚠️ Warning: The following command will delete all volumes, including database and object storage data. Proceed with caution!

docker compose -f docker/demo/docker-compose.demo.yml down -v

To remove demo-related Docker images:

# List images
docker images | grep mega

# Remove specific image
docker rmi <image_id>

docker compose -f docker/demo/docker-compose.demo.yml logs -f

# Mega backend
docker compose -f docker/demo/docker-compose.demo.yml logs -f mega

# Mega UI
docker compose -f docker/demo/docker-compose.demo.yml logs -f mega_ui

# Orion Server
docker compose -f docker/demo/docker-compose.demo.yml logs -f orion_server

# Orion Build Client
docker compose -f docker/demo/docker-compose.demo.yml logs -f orion_build_client

# Campsite API
docker compose -f docker/demo/docker-compose.demo.yml logs -f campsite_api

# PostgreSQL
docker compose -f docker/demo/docker-compose.demo.yml logs -f postgres

# MySQL
docker compose -f docker/demo/docker-compose.demo.yml logs -f mysql

# Redis
docker compose -f docker/demo/docker-compose.demo.yml logs -f redis

# RustFS
docker compose -f docker/demo/docker-compose.demo.yml logs -f rustfs

docker compose -f docker/demo/docker-compose.demo.yml logs --tail=100 <service_name>

docker compose -f docker/demo/docker-compose.demo.yml logs --since 10m <service_name>

The demo environment includes the following services:

• Infrastructure:

  • postgres: PostgreSQL database (used by Mega and Orion Server)
  • mysql: MySQL database (used by the Campsite API)
  • redis: Redis cache
  • rustfs: RustFS object storage (S3-compatible)

• Application services:

  • mega: Mega backend (Rust)
  • mega_ui: Mega Web UI (Next.js, unified image with runtime NEXT_PUBLIC_* injection)
  • orion_server: Orion build server (Rust)
  • campsite_api: Campsite API (Ruby/Rails, built locally by default; if you have the encrypted development credentials configured you can pull the pre-built image directly via CAMPSITE_API_IMAGE=public.ecr.aws/m8q5m4u3/mega/campsite-api:latest)

Previously each environment shipped its own UI image tag (demo-latest, gitmono-latest, etc.) with URLs baked in at build time. The current flow uses one mega-ui:latest image for every environment:

1. Build (moon/apps/web/Dockerfile): compile with placeholder URLs from moon/apps/web/.env.runtime.
2. Start (moon/apps/web/docker-entrypoint.sh): replace placeholders in the compiled assets with NEXT_PUBLIC_* values from the container environment, then run node server.js.
3. Configure locally: set the NEXT_PUBLIC_* block in docker/demo/.env (see .env.example). Defaults in docker-compose.demo.yml already target the gitmono.local demo hostnames.

To build the UI image locally instead of pulling from ECR:

./scripts/demo/build-demo-images-local.sh mega-ui
# then in docker/demo/.env:
# MEGA_UI_IMAGE=public.ecr.aws/m8q5m4u3/mega/mega-ui:latest-<arch>

Replace <arch> with arm64 or amd64 to match your machine.

For a detailed architecture diagram and dependency list, see the Mega / Orion Demo architecture design document.

If you run into issues, you can:

1. Read the FAQ section of this document.
2. Check the service logs for troubleshooting.

⚠️ This Docker Compose configuration is intended for local demo / evaluation only and is NOT suitable for production.

The demo environment includes the following insecure settings:

• Default passwords and test users
• HTTPS disabled
• No security policies configured
• Simple data-persistence setup

Do NOT use this configuration in production!