From 56e2c91884b1020a08f64409dfe5f90a7ec52e54 Mon Sep 17 00:00:00 2001 From: toki Date: Fri, 12 Jun 2026 19:18:36 +0900 Subject: [PATCH] update workspace-ops docs: add remote-test-environments.md, update environments.md, ports.md, remote-runners.md --- .workspace-ops/docs/environments.md | 6 ++- .workspace-ops/docs/ports.md | 6 ++- .workspace-ops/docs/remote-runners.md | 8 +++- .../docs/remote-test-environments.md | 48 +++++++++++++++++++ 4 files changed, 62 insertions(+), 6 deletions(-) create mode 100644 .workspace-ops/docs/remote-test-environments.md diff --git a/.workspace-ops/docs/environments.md b/.workspace-ops/docs/environments.md index 0e79a34..b9c068c 100644 --- a/.workspace-ops/docs/environments.md +++ b/.workspace-ops/docs/environments.md @@ -15,10 +15,11 @@ | 프로젝트 | 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`. | +| `iop` | Docker compose 기반 Control Plane, Edge, Node, Client, PostgreSQL, Redis. work container 안 Docker-in-Docker는 피한다. dev profile은 local/test 조건을 유지하되 `.env.dev.example`으로 host publish 포트만 분리한다. | `ssh toki@toki-labs.com`, `/Users/toki/agent-work/iop-dev` | workspace 기준 프로젝트. local/test frontend `13000`, backend `18000`, artifact/model `18080/18081`, wire `19080/19081/19090`, metrics `19092`, DB/cache `15400/16300`. dev frontend `13001`, backend `18001`, wire `19001/19002/19003`, DB/cache `15401/16301`, optional artifact/model `18082/18083`, metrics `19101`. | | `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 기준을 유지한다. | +| `oto` | 기본 local 테스트 evidence는 remote runner 기준. OTO Core product fallback `127.0.0.1:8080`, runner typed-command tests, Flutter client는 compatibility 경로로 유지 | `ssh toki@toki-labs.com`, `/Users/toki/agent-work/oto` | frontend `13020`, backend/Core HTTP `18020`. `make core-run`은 `OTO_CORE_ADDR=0.0.0.0:18020`, `make client-run-web`은 preview `13020`을 사용한다. `OTO_RUNNER_RELEASE_BASE_URL`은 HTTPS release URL 기준을 유지하되 private host 원문은 기록하지 않는다. | +| `appsok` | 기본 local 테스트 evidence는 standard remote Mac runner 기준. 현재 checkout의 `git diff --check`와 문법 수준 확인은 preflight로만 사용 | `ssh toki@toki-labs.com`, `$HOME/docker/services/code-server/data/volume/workspace/appsok` | Flutter/macOS build는 public port 없음. Flutter web preview가 필요하면 frontend `13050`을 사용한다. Jenkins/ADB/Xcode/Keychain credential 원문은 tracked 문서에 쓰지 않는다. | | `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 자체 포트 없음. | @@ -31,3 +32,4 @@ - README, `.env.example`, `agent-test/local/*`, smoke command, client config가 서로 다른 기본값을 말하지 않도록 맞춘다. - DB/Redis host publish 변경은 로컬 도구와 외부 접속 필요 여부를 확인한 뒤 진행한다. - field runtime에서 이미 쓰는 `18080`, `18081`, `19080`, `19090`, `18065`, `18066`은 먼저 compatibility baseline으로 취급한다. +- 프로젝트별 원격 테스트 환경과 포트 충돌 관리는 `.workspace-ops/docs/remote-test-environments.md`를 함께 확인한다. diff --git a/.workspace-ops/docs/ports.md b/.workspace-ops/docs/ports.md index e3b5ba9..7df56e6 100644 --- a/.workspace-ops/docs/ports.md +++ b/.workspace-ops/docs/ports.md @@ -28,11 +28,12 @@ | 프로젝트 | 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` 유지/변경 검토 | +| `iop` | `13000` (`dev:13001`) | `18000` (`dev:18001`) | `18080`, `18081` (`dev 후보:18082/18083`) | `19080`, `19081`, `19090` (`dev:19001/19002/19003`) | `19092` (`dev 후보:19101`) | `15400`, `16300` (`dev:15401/16301`) | 기존 field 포트 `18080`, `18081`, `19080`, `19090` 유지. dev profile은 `.env.dev.example` 기준 | | `nomadcode` | `13010` | `18010` | - | IOP 경유 | - | `15410`, `16310` | 기존 local core/default `8080` compatibility note 필요 | -| `oto` | `13020` | `18020` | - | - | - | - | 기존 local default `127.0.0.1:8080` compatibility note 필요 | +| `oto` | `13020` | `18020` | - | OTO-owned slot 미확정 | - | - | 기본 local 테스트 evidence는 `/Users/toki/agent-work/oto` 원격 runner 기준. 기존 product default `127.0.0.1:8080`은 compatibility fallback | | `alt` | `13030` | `18030`, `18031` | - | `19030` optional | - | `15430`, `16330` | 기존 API/worker 포트와 migration note 필요 | | `nexo` | `13040` | `18065`, `18066` 유지 | - | - | - | compose-internal 우선 | 변경 필요 시 `18040` 계열 후보. `18065/18066`은 compatibility baseline | +| `appsok` | `13050` | - | - | - | - | - | remote Mac runner 중심. 일반 Flutter/macOS build는 public port 없음 | | `proto-socket` | - | - | - | test runner `29090-29899` | - | - | 운영 포트가 아니라 crosstest local fixed port 예외 | ## 제외 또는 host 의존 @@ -53,3 +54,4 @@ | `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` | +| `appsok` | 현재 workspace-level inventory로 관리. 프로젝트 milestone 확인 시 추가 | diff --git a/.workspace-ops/docs/remote-runners.md b/.workspace-ops/docs/remote-runners.md index 5f61845..4eebb24 100644 --- a/.workspace-ops/docs/remote-runners.md +++ b/.workspace-ops/docs/remote-runners.md @@ -8,11 +8,12 @@ | 프로젝트 | 접속/호스트 | 원격 경로 | 용도 | 메모 | |---|---|---|---|---| | `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 기준으로 검증한다. | +| `iop` | `ssh toki@toki-labs.com` | `/Users/toki/agent-work/iop-dev` | 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를 전제로 한다. | +| `appsok` | `ssh toki@toki-labs.com` | `$HOME/docker/services/code-server/data/volume/workspace/appsok` | Flutter macOS/Xcode/ADB/Jenkins remote validation | Flutter web preview가 필요하면 `13050`을 사용한다. | | `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가 확인되면 이 문서에 추가한다. | +| `oto` | `ssh toki@toki-labs.com` | `/Users/toki/agent-work/oto` | OTO runner/Core/client remote validation | 기본 local 테스트 evidence는 remote runner 기준이다. Core `18020`, Flutter web preview `13020`을 project-owned slot으로 사용한다. | ## Remote / Field 포트 기준 @@ -30,6 +31,9 @@ | `alt` | field metrics / specialized reserve | `19092`, `19190` | | `nexo` | external core HTTP | `18065` | | `nexo` | push-proxy HTTP | `18066` | +| `appsok` | Flutter web preview when needed | `13050` | +| `oto` | Core HTTP host publish | `18020` | +| `oto` | Flutter web preview when needed | `13020` | | `proto-socket` | crosstest local fixed port range | `29090-29899` | ## 운영 메모 diff --git a/.workspace-ops/docs/remote-test-environments.md b/.workspace-ops/docs/remote-test-environments.md new file mode 100644 index 0000000..1a222b1 --- /dev/null +++ b/.workspace-ops/docs/remote-test-environments.md @@ -0,0 +1,48 @@ +# Workspace Remote Test Environments + +이 문서는 workspace 하위 프로젝트의 원격 테스트 환경, 원격 checkout, 공개/host publish 포트, 충돌 관리 기준을 한곳에서 보기 위한 운영 인벤토리다. + +상세 실행 명령과 최종 테스트 기준은 각 프로젝트의 `agent-test/local/`, compose/env example, project rule을 따른다. 이 문서는 raw secret, token, password, private key, 계정 password, private endpoint 원문을 기록하지 않는다. + +## 관리 기준 + +- 현재 Codex/container local 환경에서는 Docker-in-Docker, macOS, Android/ADB, browser/device runtime evidence를 기본 검증 환경으로 보지 않는다. +- 원격 runner를 사용할 때는 원격 checkout branch/HEAD와 local 변경 동기화 여부를 먼저 확인한다. 동기화되지 않은 원격 실행은 현재 변경 검증으로 보지 않는다. +- 포트는 `project-owned test slot`과 `shared field/runtime baseline`을 분리해 기록한다. +- 컨테이너 내부 listen 포트는 제품/프레임워크 기본값을 우선 유지하고, workspace 표준화 대상은 host publish, preview, remote runner 문서, smoke command다. +- ignored local file은 inventory 근거로만 보고, 값 자체를 중앙 tracked 문서로 복사하지 않는다. + +## 원격 테스트 환경 표 + +| 프로젝트 | 원격 테스트 환경 | 원격 checkout / 기준 위치 | 원격 검증 용도 | Project-owned test slots | Shared / field baseline | Secret / private input | +|---|---|---|---|---|---|---| +| `appsok` | `ssh toki@toki-labs.com` standard remote Mac runner | `$HOME/docker/services/code-server/data/volume/workspace/appsok` | Flutter macOS, Xcode, Keychain, ADB, Jenkins 연동 검증 | Flutter web preview `13050` when needed | 일반 unit/analyze/macOS build는 public port 없음 | Jenkins credential, SSH password, signing/notary credential은 remote Keychain 또는 사용자 제공 값만 사용 | +| `alt` | 필요 시 `ssh toki@toki-labs.com` | `~/agent-work/alt` | Docker-backed PostgreSQL/Redis, platform/device/browser runtime, 외부 provider/live smoke | frontend `13030`, API/worker `18030/18031`, optional wire/evidence relay `19030`, DB/cache `15430/16330` | field reserve `13000-13099`, artifact/model `18080/18081`, wire `19080/19090`, metrics `19092`, specialized `19190`는 shared baseline으로만 취급 | KIS/live provider credential은 private rule 또는 secret-only profile에서만 사용 | +| `iop` | `ssh toki@toki-labs.com`, code-server/remote runner | `/Users/toki/agent-work/iop-dev` | Control Plane, Edge, Node, Client, Docker compose, field/bootstrap 검증 | local/test: frontend `13000`, CP HTTP `18000`, DB/cache `15400/16300`; dev: frontend `13001`, CP HTTP `18001`, DB/cache `15401/16301` | local/test field baseline `18080/18081`, `19080/19081/19090`, metrics `19092`; dev wire/model candidates `19001/19002/19003`, `18082/18083`, metrics `19101` | Edge token 등 secret 원문은 원격 환경에서 주입하고 tracked 문서에 기록하지 않음 | +| `nexo` | `ssh toki@toki-labs.com` | repo `~/agent-work/nexo`, compose `~/docker/agent-service/nexo/compose` | Mattermost core/push-proxy runtime, Flutter/Android, Detox, FCM/device evidence | core `18065`, push-proxy `18066` | Android Detox Metro는 `8081` 점유 시 `8088`; Flutter Web preview는 ignored `web-smoke.env` 값 기준 | Mattermost/FCM/test account 값은 `agent-test/local/secrets.md` 같은 ignored profile에서만 확인 | +| `nomadcode` | `ssh toki@toki-labs.com` standard remote runner | `$HOME/agent-work/nomadcode` | Core, Flutter client, Android SDK runner, Mattermost/FCM 시나리오 | Flutter/code-server preview `13010`, Core compose host publish `18010:8080`, DB/cache 후보 `15410/16310` | sibling `../nexo/packages/messaging_flutter`, `../proto-socket/dart` 경로 전제 | Mattermost/FCM/signature 등 private input은 ignored local profile 기준 | +| `proto-socket` | 기본은 local matrix; Dart.web Chrome 없을 때 remote fallback | `toki@toki-labs.com`, `~/agent-work/proto-socket-dart-web` | Dart.web/WSS Chrome fallback, SPKI wrapper, cross-language matrix 보조 | crosstest runner fixed range `29090-29899` | runtime service port 없음; 예제 `9090`은 제품/테스트 슬롯 아님 | runner 입력 secret 없음. SSH 인증은 local 계정/agent 환경 책임 | +| `oto` | `ssh toki@toki-labs.com` standard remote runner | `/Users/toki/agent-work/oto` | OTO runner, Core HTTP, Flutter client/web preview, bootstrap/release validation | frontend/web preview `13020`, Core HTTP host publish `18020` | product fallback `127.0.0.1:8080`은 compatibility 경로. OTO-owned wire/agent transport port는 아직 확정하지 않음 | `OTO_RUNNER_RELEASE_BASE_URL`, enrollment token, private release host 원문은 tracked 문서에 기록하지 않음 | +| `agent-shell` | 없음 | 없음 | Dart/Flutter package test | 없음 | package 자체 포트 없음. host 앱이 환경 소유 | 없음 | +| `dart-app-core` | 없음 | 없음 | Dart library tests | 없음 | library 자체 포트 없음 | 없음 | +| `agentic-framework` | 없음 | 없음 | agent-ops framework/docs | 없음 | 서버/runtime 포트 없음 | 없음 | + +## 포트 충돌 관리 + +| 항목 | 상태 | 조치 | +|---|---|---| +| `appsok` preview vs `nomadcode` preview | 기존 `appsok` 문서가 `13010+`를 언급해 `nomadcode` `13010`과 충돌 가능 | `appsok` project-owned preview slot을 `13050`으로 고정한다. | +| `alt` field reserve `13000-13099` vs 프로젝트별 preview slots | field/shared reserve가 전체 frontend 대역을 넓게 표현함 | `alt` 자체 preview는 `13030`으로 보고, field reserve는 shared baseline으로 분리한다. | +| `iop` shared field ports | `18080/18081/19080/19090/19092`가 다른 프로젝트 smoke에서도 참조됨 | IOP-owned runtime baseline으로 유지하되 다른 프로젝트의 project-owned slot으로 재사용하지 않는다. | +| `iop` dev profile | local/test stack이 원격 host에서 이미 `13000`, `18000`, `19080`, `19081`, `15400`, `16300`을 점유할 수 있음 | dev profile은 `.env.dev.example` 기준 `13001`, `18001`, `19001`, `19002`, `19003`, `15401`, `16301`을 사용하고 compose project/network를 분리한다. | +| `oto` remote local profile | 제품 fallback `127.0.0.1:8080`과 workspace backend slot `18020`이 함께 존재함 | 테스트/원격 evidence는 `18020`을 기준으로 하고 `8080`은 product compatibility fallback으로만 문서화한다. | +| `nexo` `18065/18066` | workspace backend 후보 `18040` 계열과 다름 | Mattermost compatibility baseline으로 유지한다. 신규 nexo-owned backend가 필요할 때만 `18040` 계열을 검토한다. | +| `proto-socket` `29090-29899` | 일반 runtime port가 아니라 test runner fixed range | workspace 예외 대역으로 유지하고 제품 host publish 표준화 대상에서 제외한다. | + +## 변경 전 체크리스트 + +- 원격 checkout이 현재 작업과 동기화되어 있는지 확인한다. +- 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가 서로 다른 기본값을 말하지 않도록 맞춘다. +- field/runtime 포트는 문서 정리만으로 바꾸지 않는다. 변경 전 smoke, client config, remote runner path를 같이 확인한다.