browser/openspec/changes/add-local-docker-deployment/design.md

Design

Deployment shape

The local Docker deployment runs three services:

• platform: Go backend listening on :8080, using file-backed storage under /data/platform.
• run: Go worker in worker mode, connecting to http://platform:8080, using /data/run/workspace and /data/run/spool.
• platform_web: static Vite build served by Nginx, proxying /api/v1 and /healthz to platform:8080.

This matches the current architecture without introducing a new database adapter. The platform metadata and segmented log bodies are persisted in a Docker named volume. The worker has its own named volume for local workspace and spool data.

Local debugging

Direct local execution remains environment-variable based:

• Root .env.example documents the common three-process setup.
• platform/.env.example documents backend storage knobs.
• run/.env.example documents worker identity, platform URL, workspace, and scheduling knobs.
• platform_web/.env.example documents Vite browser API and dev proxy knobs.

Developers can copy the example files to .env or source/export the variables before running go run / npm run dev. The project intentionally keeps Go config loading simple and does not require a checked-in secret-bearing config file.

Storage guidance

The Docker compose default uses the durable file backend because it works without external services:

• PLATFORM_METADATA_PATH=/data/platform/metadata.json
• PLATFORM_LOG_DIR=/data/platform/logs

For larger production deployments, MySQL/Postgres should be introduced as a metadata repository adapter in a future OpenSpec change. High-volume log bodies should use a log-optimized backend such as ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments behind LogBodyStore; Docker compose does not pretend that MySQL is an adequate row-per-log-line body store.