first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,32 @@
+# 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.
+
@@ -0,0 +1,19 @@
+# Add local Docker deployment
+
+## Why
+
+Operators need a repeatable way to run the platform backend, run worker, and platform web console with persistent local data. Local debugging also needs clear environment files so storage paths, run identity, platform API proxying, and browser-facing API URLs are easy to modify without changing code.
+
+## What Changes
+
+- Add Dockerfiles for `platform/`, `run/`, and `platform_web/`.
+- Add a root `docker-compose.yml` that starts platform, run worker, and web console with named volumes for platform data and run workspace/spool data.
+- Add local `.env.example` files documenting the runtime variables for Docker and direct local execution.
+- Update README files to explain Docker deployment, local direct execution, and which config files to edit.
+
+## Impact
+
+- Adds local deployment configuration only; it does not add billing, cloud host sales, external provider workflows, or production log database adapters.
+- Keeps platform data durable through mounted volumes and the existing file storage backend.
+- Keeps frontend/browser access platform-mediated through `/api/v1` proxying.
+
@@ -0,0 +1,37 @@
+# local-docker-deployment Specification
+
+## ADDED Requirements
+
+### Requirement: Docker deployment files
+
+The repository SHALL provide a local Docker deployment that starts the platform backend, run worker, and platform web console.
+
+#### Scenario: Compose starts local services with persistent directories
+
+- **GIVEN** an operator runs the local compose file
+- **WHEN** the services start
+- **THEN** the platform SHALL use a durable mounted data directory
+- **AND** the run worker SHALL use a mounted workspace/spool directory
+- **AND** the web console SHALL proxy platform API calls through platform-owned routes.
+
+### Requirement: Local debugging configuration examples
+
+The repository SHALL document direct local execution configuration through example environment files.
+
+#### Scenario: Developer wants to change ports or storage paths
+
+- **GIVEN** a developer wants to run the platform, run worker, and web console directly
+- **WHEN** they inspect the environment examples
+- **THEN** they SHALL find the platform listen address, storage backend, metadata path, log directory, run platform URL, run workspace/spool roots, and web API/proxy settings.
+
+### Requirement: Storage guidance remains scoped
+
+The deployment documentation SHALL distinguish metadata storage from log body storage.
+
+#### Scenario: Operator asks where large server logs should go
+
+- **GIVEN** a deployment with hundreds or thousands of servers
+- **WHEN** the operator reads the deployment guidance
+- **THEN** it SHALL say relational databases are for metadata and indexes
+- **AND** it SHALL recommend log-optimized backends for high-volume log bodies in future adapters.
+
@@ -0,0 +1,22 @@
+## 1. OpenSpec Artifacts
+
+- [x] 1.1 Create proposal, design, spec, and tasks for local Docker deployment and debugging configuration.
+- [x] 1.2 Validate the change with `openspec validate add-local-docker-deployment --strict`.
+
+## 2. Docker Deployment
+
+- [x] 2.1 Add Dockerfiles for platform, run, and platform_web.
+- [x] 2.2 Add a root compose file with persistent volumes and safe service wiring.
+- [x] 2.3 Add Docker ignore rules to keep builds small and avoid copying local data.
+
+## 3. Local Debug Configuration
+
+- [x] 3.1 Add example environment files for root orchestration, platform, run, and platform_web.
+- [x] 3.2 Document which variables to modify for Docker and direct local execution.
+
+## 4. Verification
+
+- [x] 4.1 Validate compose syntax with `docker compose config`.
+- [x] 4.2 Run focused backend tests for platform and run config packages.
+- [x] 4.3 Run `scripts/check-structure.sh`.
+- [x] 4.4 Run `openspec validate add-local-docker-deployment --strict`.