From a5f6d0e132c1562c75e9894e1c11f5ca456031d3 Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 7 Jun 2026 10:28:02 +0900 Subject: [PATCH] Add workspace operations docs --- .gitignore | 4 +++ workspace-ops/environments.md | 33 ++++++++++++++++++++ workspace-ops/ports.md | 55 +++++++++++++++++++++++++++++++++ workspace-ops/remote-runners.md | 40 ++++++++++++++++++++++++ 4 files changed, 132 insertions(+) create mode 100644 workspace-ops/environments.md create mode 100644 workspace-ops/ports.md create mode 100644 workspace-ops/remote-runners.md diff --git a/.gitignore b/.gitignore index c47c4b2..400aa6b 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,10 @@ !/.workspace-skills/ !/.workspace-skills/** +# Workspace-owned operations docs. +!/workspace-ops/ +!/workspace-ops/** + # Generated or local-only directories should stay ignored even if an allowed # directory is added later. /mattermost/ diff --git a/workspace-ops/environments.md b/workspace-ops/environments.md new file mode 100644 index 0000000..0e79a34 --- /dev/null +++ b/workspace-ops/environments.md @@ -0,0 +1,33 @@ +# Workspace Environments + +이 문서는 하위 프로젝트의 local/test/runtime 환경을 workspace 관점에서 요약한다. +상세 구현과 최종 source of truth는 각 프로젝트의 `agent-test/local/`, compose/env example, roadmap milestone에 둔다. + +## 공통 기준 + +- tracked 문서에는 raw secret, token, password, private key, 계정 id를 쓰지 않는다. +- ignored local file은 inventory 근거로만 보고, 값 자체를 복사하지 않는다. +- 원격 runtime 포트 변경은 compose/env/smoke/client config 영향 확인 뒤 프로젝트별 마일스톤에서 처리한다. +- host publish 표준화와 container 내부 listen 포트 변경은 별도 문제로 다룬다. + +## 프로젝트별 환경 요약 + +| 프로젝트 | Local / Test 환경 | Remote / Runtime 환경 | 포트/환경 메모 | +|---|---|---|---| +| `alt` | Go workspace, Flutter client, local PostgreSQL/Redis compose, KIS smoke는 private testing env 의존 | `ssh toki@toki-labs.com`, `~/agent-work/alt` | API/worker 후보 `18030/18031`, frontend `13030`, optional wire `19030`, DB/cache `15430/16330`. KIS credential은 tracked 문서에 쓰지 않는다. | +| `iop` | Docker compose 기반 Control Plane, Edge, Node, Client, PostgreSQL, Redis. work container 안 Docker-in-Docker는 피한다. | `ssh toki@toki-labs.com`, `/Users/toki/agent-work/iop` | workspace 기준 프로젝트. frontend `13000`, backend `18000`, artifact/model `18080/18081`, wire `19080/19081/19090`, metrics `19092`, DB/cache `15400/16300`. | +| `nexo` | Mattermost core, webapp, push-proxy, Flutter test host, upstream dev compose | `ssh toki@toki-labs.com`, repo `~/agent-work/nexo`, compose `~/docker/agent-service/nexo/compose` | core `18065`, push-proxy `18066`은 compatibility baseline. upstream dev compose 포트는 nexo-owned runtime 포트와 분리한다. | +| `nomadcode` | Core local default `8080`, Docker compose DB/Redis, Flutter client, code-server preview | Android runner `$HOME/agent-work/nomadcode`, sibling `../nexo/packages/messaging_flutter`, `../proto-socket/dart` | frontend 후보 `13010`, backend 후보 `18010`, DB/cache `15410/16310`. Plane, Mattermost, Jira, IOP Edge endpoint는 secret 없이 책임 경계만 기록한다. | +| `oto` | OTO Core local default `127.0.0.1:8080`, runner/local typed-command tests, Flutter client | 표준 remote runner 없음 | frontend 후보 `13020`, backend 후보 `18020`. `OTO_RUNNER_RELEASE_BASE_URL`은 HTTPS release URL 기준을 유지한다. | +| `proto-socket` | same-language/cross-language test matrix, examples, per-language runners | Dart web/Chrome fallback: `ssh toki@toki-labs.com`, `~/agent-work/proto-socket-dart-web` | runtime 포트 없음. fixed crosstest local port `29090-29899`는 workspace 표준 예외. 예제 `9090`은 제품 host publish 포트로 보지 않는다. | +| `agent-shell` | Dart/Flutter package test | 없음 | package 자체 포트 없음. | +| `dart-app-core` | Dart library tests | 없음 | library 자체 포트 없음. | +| `agentic-framework` | agent-ops framework/docs | 없음 | 서버/runtime 포트 없음. 포트 마일스톤 대상에서 제외한다. | + +## 변경 전 확인 항목 + +- compose host publish 변경인지, container 내부 listen 변경인지 먼저 구분한다. +- remote runner, code-server proxy, Android/Detox/Flutter Web smoke가 같은 포트를 참조하는지 확인한다. +- README, `.env.example`, `agent-test/local/*`, smoke command, client config가 서로 다른 기본값을 말하지 않도록 맞춘다. +- DB/Redis host publish 변경은 로컬 도구와 외부 접속 필요 여부를 확인한 뒤 진행한다. +- field runtime에서 이미 쓰는 `18080`, `18081`, `19080`, `19090`, `18065`, `18066`은 먼저 compatibility baseline으로 취급한다. diff --git a/workspace-ops/ports.md b/workspace-ops/ports.md new file mode 100644 index 0000000..e3b5ba9 --- /dev/null +++ b/workspace-ops/ports.md @@ -0,0 +1,55 @@ +# Workspace Ports + +이 문서는 workspace 하위 프로젝트의 host publish port, dev preview port, wire port, test runner port를 한눈에 보기 위한 운영 표다. +컨테이너 내부 포트와 제품 기본 listen 포트는 가능한 유지하고, workspace 표준화 대상은 host publish, preview, remote runner 문서, smoke command로 둔다. + +## 원칙 + +- 컨테이너 내부 포트는 각 제품/프레임워크의 표준값을 우선 유지한다. +- 외부 검증이나 원격 runner에서 이미 쓰는 포트는 바로 바꾸지 않고 프로젝트별 마일스톤에서 영향 범위를 확인한다. +- DB/Redis는 Docker network DNS를 우선하고, host publish가 필요한 경우에만 project offset 포트를 둔다. +- secret, token, password, private endpoint 원문은 tracked 문서에 쓰지 않는다. +- runtime service port가 없는 package는 포트 표준화 대상에서 제외한다. +- `proto-socket`처럼 운영 서버가 아니라 test runner가 고정 포트를 쓰는 경우는 예외 대역으로 문서화한다. + +## 권장 대역 + +| 용도 | 대역 | 설명 | +|---|---:|---| +| Frontend / Web preview | `13000-13099` | Flutter Web, static preview, code-server proxy host port | +| Backend HTTP/API | `18000-18079` | 제품 API, core server, app backend host publish | +| Artifact/bootstrap/model HTTP | `18080-18099` | artifact server, bootstrap, Edge OpenAI-compatible, A2A HTTP | +| Wire / agent transport | `19000-19099` | proto-socket, Control Plane wire, Edge-Node TCP | +| Metrics / diagnostics | `19100-19199` | metrics, diagnostic HTTP/TCP. 기존 `1909x`는 migration 전까지 허용 | +| DB host publish | `15400-15499` | PostgreSQL host publish가 반드시 필요한 경우 | +| Cache host publish | `16300-16399` | Redis host publish가 반드시 필요한 경우 | + +## 프로젝트별 슬롯 + +| 프로젝트 | Frontend / Preview | Backend / API | Artifact / Model | Wire / Agent Transport | Metrics | DB / Cache | 메모 | +|---|---:|---:|---:|---:|---:|---:|---| +| `iop` | `13000` | `18000` | `18080`, `18081` | `19080`, `19081`, `19090` | `19092` | `15400`, `16300` | 기존 field 포트 `18080`, `18081`, `19080`, `19090` 유지/변경 검토 | +| `nomadcode` | `13010` | `18010` | - | IOP 경유 | - | `15410`, `16310` | 기존 local core/default `8080` compatibility note 필요 | +| `oto` | `13020` | `18020` | - | - | - | - | 기존 local default `127.0.0.1:8080` compatibility note 필요 | +| `alt` | `13030` | `18030`, `18031` | - | `19030` optional | - | `15430`, `16330` | 기존 API/worker 포트와 migration note 필요 | +| `nexo` | `13040` | `18065`, `18066` 유지 | - | - | - | compose-internal 우선 | 변경 필요 시 `18040` 계열 후보. `18065/18066`은 compatibility baseline | +| `proto-socket` | - | - | - | test runner `29090-29899` | - | - | 운영 포트가 아니라 crosstest local fixed port 예외 | + +## 제외 또는 host 의존 + +| 프로젝트 | 상태 | 메모 | +|---|---|---| +| `agent-shell` | 제외 | package 자체 포트 없음. host 앱이 환경을 소유한다. | +| `dart-app-core` | 제외 | library 자체 포트 없음. | +| `agentic-framework` | 제외 | 서버/runtime 포트 없음. 공통 agent-ops 문서 repo로만 본다. | + +## 관련 마일스톤 + +| 프로젝트 | 마일스톤 | +|---|---| +| `alt` | `agent-roadmap/phase/trading-expansion/milestones/workspace-port-env-standardization.md` | +| `iop` | `agent-roadmap/phase/automation-runtime-bridge/milestones/workspace-port-env-standardization.md` | +| `nexo` | `agent-roadmap/phase/messaging-runtime/milestones/workspace-port-env-standardization.md` | +| `nomadcode` | `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/workspace-port-env-standardization.md` | +| `oto` | `agent-roadmap/phase/independent-control-plane/milestones/workspace-port-env-standardization.md` | +| `proto-socket` | `agent-roadmap/milestones/workspace-port-env-standardization.md` | diff --git a/workspace-ops/remote-runners.md b/workspace-ops/remote-runners.md new file mode 100644 index 0000000..5f61845 --- /dev/null +++ b/workspace-ops/remote-runners.md @@ -0,0 +1,40 @@ +# Workspace Remote Runners + +이 문서는 workspace 하위 프로젝트에서 확인된 원격 runner, remote runtime path, field endpoint 성격을 정리한다. +접속 credential, token, private key, secret 값은 기록하지 않는다. + +## 원격 runner 표 + +| 프로젝트 | 접속/호스트 | 원격 경로 | 용도 | 메모 | +|---|---|---|---|---| +| `alt` | `ssh toki@toki-labs.com` | `~/agent-work/alt` | ALT 테스트/원격 작업 runner | KIS live smoke와 private testing env 값은 tracked 문서에 쓰지 않는다. | +| `iop` | `ssh toki@toki-labs.com` | `/Users/toki/agent-work/iop` | Control Plane/Edge/Node/Client remote validation | Docker-in-Docker 없이 remote host/runtime 기준으로 검증한다. | +| `nexo` | `ssh toki@toki-labs.com` | repo `~/agent-work/nexo`, compose `~/docker/agent-service/nexo/compose` | Mattermost core/push-proxy runtime validation | core `18065`, push-proxy `18066`은 compatibility baseline으로 둔다. | +| `nomadcode` | remote Android runner host | `$HOME/agent-work/nomadcode` | Flutter/Android runner, sibling package integration | `../nexo/packages/messaging_flutter`, `../proto-socket/dart` sibling dependency를 전제로 한다. | +| `proto-socket` | `ssh toki@toki-labs.com` | `~/agent-work/proto-socket-dart-web` | Dart web/Chrome fallback, WSS/SPKI wrapper | runtime service가 아니라 test harness 예외다. | +| `oto` | 없음 | 없음 | local runner 중심 | 표준 remote runner가 확인되면 이 문서에 추가한다. | + +## Remote / Field 포트 기준 + +| 프로젝트 | 포트/URL 성격 | 값 | +|---|---|---| +| `iop` | artifact/bootstrap HTTP | `18080` | +| `iop` | Edge OpenAI-compatible HTTP | `18081` | +| `iop` | Control Plane wire | `19080` | +| `iop` | Edge-Node / Edge runtime TCP | `19090` | +| `iop` | metrics 기존 field 계열 | `19092` | +| `alt` | field frontend/dev preview reserve | `13000-13099` | +| `alt` | field artifact/bootstrap | `18080` | +| `alt` | field Edge OpenAI-compatible | `18081` | +| `alt` | field CP wire / Edge runtime | `19080`, `19090` | +| `alt` | field metrics / specialized reserve | `19092`, `19190` | +| `nexo` | external core HTTP | `18065` | +| `nexo` | push-proxy HTTP | `18066` | +| `proto-socket` | crosstest local fixed port range | `29090-29899` | + +## 운영 메모 + +- 원격 포트는 문서 정리만으로 바꾸지 않는다. 변경 전에는 해당 프로젝트 마일스톤에서 smoke, client config, remote runner path를 같이 확인한다. +- field/runtime 포트와 local development 후보 포트가 다를 수 있다. 이 경우 field 포트를 compatibility baseline으로 먼저 둔다. +- `proto-socket`의 remote runner는 제품 runtime이 아니라 Dart web/Chrome test harness 보조 경로다. +- private host 값은 이미 공개된 host 별칭 수준만 기록하고, credential이나 token은 기록하지 않는다.