From 796feca33dc752efbb5d220880c3d4da470cca19 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 8 Jun 2026 09:46:07 +0900 Subject: [PATCH] =?UTF-8?q?chore(workspace):=20=EC=9B=90=EA=B2=A9=20?= =?UTF-8?q?=ED=85=8C=EC=8A=A4=ED=8A=B8=20=ED=8F=AC=ED=8A=B8=20=EA=B8=B0?= =?UTF-8?q?=EC=A4=80=EC=9D=84=20=EB=A7=9E=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 기본 local 테스트 환경이 standard remote runner라는 전제에 맞춰 문서와 로드맵 기준을 정리한다. Core compose host publish 기본값을 18010으로 맞추고 8080 호환은 명시적 override로 남긴다. --- README.md | 15 ++++++++++ agent-roadmap/ROADMAP.md | 4 +-- .../agent-ops-mcp-control-plane/PHASE.md | 6 ++-- .../workspace-port-env-standardization.md | 28 +++++++++++-------- apps/client/README.md | 8 ++++++ .../notes/flutter-core-api-candidates.md | 13 +++++++++ services/core/README.md | 14 ++++++++++ services/core/docker-compose.yml | 2 +- 8 files changed, 73 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index b2ca90d..7b4b90d 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,19 @@ flutter run | core build | `cd services/core && ./bin/build` | 기본 출력 경로는 `.build/nomadcode-core`입니다. | | client 테스트 | `cd apps/client && flutter test` | Flutter test suite입니다. | +## 포트와 endpoint 표준 + +현재 runtime 기본값은 기존 local 개발 흐름을 깨지 않도록 유지하고, workspace/remote runner에서 외부로 노출하는 포트만 공통 대역으로 정렬합니다. + +| 표면 | 현재 compatibility baseline | workspace 기준 | 비고 | +|------|-----------------------------|----------------|------| +| Flutter web/code-server preview | local smoke에서 빈 포트를 고르고 `/proxy//` base href를 사용합니다. 기존 예시는 `8081`입니다. | 안정적인 workspace preview는 `13010`부터 사용하고 병렬 preview는 `13011`, `13012`처럼 증가시킵니다. | code-server가 proxy prefix를 유지하거나 제거해도 정적 리소스가 열려야 합니다. | +| code-server workspace entry | client mock workspace URL은 `http://localhost:8080/?folder=...`를 사용합니다. | 유지 | 이 값은 code-server entry URL 호환성이고 Flutter preview 포트가 아닙니다. | +| Core HTTP/API | process/container 내부 기본값은 `HTTP_ADDR=:8080`, Docker `EXPOSE 8080`, local curl 예시는 `localhost:8080`입니다. | compose host publish 기본값은 `18010:8080`입니다. | 기존 `8080` local default는 migration compatibility로 유지하고, compose에서 필요하면 `NOMADCODE_CORE_HOST_PORT=8080`으로 되돌립니다. | +| PostgreSQL | compose와 local script는 `code-server-postgres:5432` service DNS를 사용합니다. | host 노출이 꼭 필요하면 `15410:5432`를 후보로 둡니다. | 기본은 service DNS이며 host publish를 추가하지 않습니다. | +| Redis | compose와 local script는 `code-server-redis:6379` service DNS를 사용합니다. | host 노출이 꼭 필요하면 `16310:6379`를 후보로 둡니다. | 기본은 service DNS이며 host publish를 추가하지 않습니다. | +| IOP Edge / provider endpoints | `MODEL_*`, `A2A_*`, `PROTO_SOCKET_*`, `PLANE_*`, `JIRA_*`, `MATTERMOST_*` env로 분리합니다. | public port를 예약하지 않고 각 provider endpoint를 env로 주입합니다. | token, password, API key 원문은 tracked 문서에 쓰지 않고 ignored local env/secret 파일에서만 관리합니다. | + ## 구조 | 경로 | 역할 | @@ -125,8 +138,10 @@ IOP 경계가 걸린 작업은 같은 workspace에 sibling IOP repository가 있 | Core | `DATABASE_URL` | 스크립트 사용 시 선택 | Core script는 local 기본값을 제공합니다. 다른 PostgreSQL을 쓰거나 binary를 직접 실행할 때 설정합니다. | | Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | 스크립트 사용 시 선택 | worker/queue 상태에 사용할 Redis 주소와 key prefix입니다. | | Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | 선택 | `AUTH_PASSWORD`를 설정하면 `/readyz`와 `/api/*`에 HTTP Basic Auth가 적용됩니다. | +| Core | `NOMADCODE_CORE_HOST_PORT` | 선택 | Docker Compose host publish 포트입니다. 기본값은 remote/local test workspace 기준 `18010`이고 container 내부는 `8080`입니다. | | Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | 선택 | worker execution에서 사용할 IOP Edge OpenAI-compatible Responses endpoint 설정입니다. IOP/NomadCode 전용 실행 문맥은 요청 `metadata`로 전달하는 방향을 기준으로 합니다. | | Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | 선택 | 향후 A2A-compatible agent delegation 경로 설정입니다. 현재 기본 실행 경로는 아닙니다. | +| Core/Client | `PROTO_SOCKET_PATH`, `PROTO_SOCKET_HEARTBEAT_INTERVAL_SEC`, `PROTO_SOCKET_HEARTBEAT_WAIT_SEC`, `PROTO_SOCKET_HOST`, `PROTO_SOCKET_PORT`, `PROTO_SOCKET_SECURE`, `PROTO_SOCKET_ENABLED`, `PROTO_SOCKET_HEARTBEAT_INTERVAL_SECONDS`, `PROTO_SOCKET_HEARTBEAT_WAIT_SECONDS` | 선택 | Core proto-socket endpoint와 Flutter client connector 설정입니다. Client는 host가 없으면 연결을 비활성화합니다. | | Core | `WORKFLOW_TASK_TIMEOUT_SEC` | 선택 | workflow task timeout 기본값을 조정합니다. | | Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN`, `MATTERMOST_CHANNEL_ID` | 선택 | Mattermost task completion message 발송용 설정입니다. token 값은 문서에 기록하지 않습니다. | | Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | 선택 | Plane work item 조회, comment, state update 연동용 설정입니다. token 값은 문서에 기록하지 않습니다. | diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index ae41878..a4792ea 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -4,7 +4,7 @@ NomadCode는 Flutter 기반 앱, core 서비스, 공유 계약, agent-operation 규칙을 하나의 원레포로 묶어 AI-assisted development workflow를 조율하는 프로젝트다. -현재 로드맵은 `ROADMAP.md -> phase//PHASE.md -> phase//milestones/.md` scaffold를 기준으로 관리한다. React/Vite 웹 콘솔 제거, 서버/Plane/provider 기반 작업, Flutter-first 클라이언트 정리, Mattermost push plugin extraction, client integration 표준화는 완료되었다. 현재 최상위 진행 마일스톤은 workspace 포트/환경 표준화이며, Workbench Provider Slot Composition과 work item sync 계열은 계획 후보로 둔다. +현재 로드맵은 `ROADMAP.md -> phase//PHASE.md -> phase//milestones/.md` scaffold를 기준으로 관리한다. React/Vite 웹 콘솔 제거, 서버/Plane/provider 기반 작업, Flutter-first 클라이언트 정리, Mattermost push plugin extraction, client integration 표준화는 완료되었다. workspace 포트/환경 표준화는 검토중이며, Workbench Provider Slot Composition과 work item sync 계열은 계획 후보로 둔다. IOP 외부 실행 호출은 OpenAI-compatible Responses API 방식을 기본 계약으로 채택하고, NomadCode/IOP 고유의 task, workspace, session, approval, artifact, notification 문맥은 별도 `iop` wrapper field가 아니라 `metadata` 확장으로 전달한다. A2A는 agent-to-agent delegation이 명확히 필요할 때 재검토하며, IOP native protocol은 NomadCode의 기본 외부 실행 호출 표면으로 쓰지 않는다. @@ -37,7 +37,7 @@ IOP 외부 실행 호출은 OpenAI-compatible Responses API 방식을 기본 계 - 요약: Plane 확장, Jira-compatible provider 추상화, Mattermost, IOP OpenAI-compatible Responses 호출과 metadata 기반 실행 문맥 전달을 완료했고, Phase 완료 확인과 archive 승인을 기다린다. - [진행중] Agent-Ops MCP Control Plane - 경로: `agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md` - - 요약: 로드맵 기반 agent-ops 운영 자동화, Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인, 외부 agent용 MCP 제어 표면을 다루며, 현재는 workspace 포트/환경 표준화를 최상위 진행 마일스톤으로 둔다. + - 요약: 로드맵 기반 agent-ops 운영 자동화, Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인, 외부 agent용 MCP 제어 표면을 다루며, 현재는 workspace 포트/환경 표준화 완료 확인과 work item sync 계획 후보를 함께 둔다. - [계획] Project Workspace Management UX - 경로: `agent-roadmap/phase/project-workspace-management-ux/PHASE.md` - 요약: client integration 표준화, core workflow, 외부 통합 기준 이후 프로젝트 단위 앱 UX를 다루며, provider slot 기반 외부 console composition은 계획 후보로 둔다. diff --git a/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md b/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md index 565ffc8..63266a2 100644 --- a/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md +++ b/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md @@ -6,7 +6,7 @@ ## 목표 -로드맵 기반 agent-ops 운영 루프, Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인, 외부 agent 제어 표면을 Core action과 MCP tool 계층으로 분리한다. 현재는 workspace 포트/환경 표준화를 최상위 진행 마일스톤으로 두고, work item sync와 실행 lifecycle은 계획 후보로 둔다. +로드맵 기반 agent-ops 운영 루프, Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인, 외부 agent 제어 표면을 Core action과 MCP tool 계층으로 분리한다. 현재는 workspace 포트/환경 표준화를 검토중 마일스톤으로 두고, work item sync와 실행 lifecycle은 계획 후보로 둔다. ## Milestone 흐름 @@ -14,9 +14,9 @@ 완료, 검토중, 진행중, 계획, 스케치 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다. 스케치 Milestone은 아직 구현 가능한 계획이 아니므로 계획 Milestone보다 아래에 둔다. -- [진행중] 워크스페이스 포트/환경 표준화 +- [검토중] 워크스페이스 포트/환경 표준화 - 경로: `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/workspace-port-env-standardization.md` - - 요약: NomadCode client/core/compose/test runner 포트와 IOP Edge 연동 endpoint를 workspace 공통 대역과 remote runner 문서 기준으로 정리한다. + - 요약: NomadCode client/core/compose/test runner 포트와 IOP Edge 연동 endpoint를 workspace 공통 대역과 remote runner 문서 기준으로 정리했고, 완료 확인과 archive 승인을 기다린다. - [계획] Milestone Work Item Creation Sync - 경로: `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/milestone-work-item-creation-sync.md` diff --git a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/workspace-port-env-standardization.md b/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/workspace-port-env-standardization.md index c263fa3..dcdedf6 100644 --- a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/workspace-port-env-standardization.md +++ b/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/workspace-port-env-standardization.md @@ -11,7 +11,7 @@ NomadCode의 Flutter client, core service, compose/local run, code-server previe ## 상태 -[진행중] +[검토중] ## 구현 잠금 @@ -32,20 +32,26 @@ NomadCode의 Flutter client, core service, compose/local run, code-server previe NomadCode가 직접 소유한 client/core 포트와 외부 IOP/Nexo/Plane 연동 endpoint를 현재 repo baseline 기준으로 분리해 정리한다. -- [ ] [client-preview] Flutter web/code-server preview는 현재 local smoke 기준 `8081` 계열 임시 포트와 `/proxy//` base href를 사용한다. frontend 대역 후보 `13010`으로 정리할 때 기존 preview 흐름과 workspace mock URL의 `localhost:8080` code-server entry 호환성을 기록한다. -- [ ] [core-port] Core HTTP/API는 현재 `HTTP_ADDR=:8080`, Docker `EXPOSE 8080`, compose `8080:8080` host publish를 사용한다. backend host publish 후보 `18010`으로 문서화하되, 기존 `8080` local default와 migration note를 남긴다. -- [ ] [infra-ports] PostgreSQL/Redis는 현재 compose 내부에서 `code-server-postgres:5432`, `code-server-redis:6379` service DNS를 사용하고 별도 host publish를 갖지 않는다. 필요한 경우만 DB/cache offset 대역 `15410/16310` 노출 후보를 문서화한다. -- [ ] [external-endpoints] IOP Edge OpenAI-compatible endpoint는 현재 `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC`로 설정하고, A2A/proto-socket/provider 연동은 `A2A_*`, `PROTO_SOCKET_*`, `PLANE_*`, `JIRA_*`, `MATTERMOST_*` env로 분리한다. raw secret 없이 source of truth와 책임 경계만 남긴다. +- [x] [client-preview] Flutter web/code-server preview는 현재 local smoke 기준 `8081` 계열 임시 포트와 `/proxy//` base href를 사용한다. frontend 대역 후보 `13010`으로 정리할 때 기존 preview 흐름과 workspace mock URL의 `localhost:8080` code-server entry 호환성을 기록한다. +- [x] [core-port] Core HTTP/API는 `HTTP_ADDR=:8080`, Docker `EXPOSE 8080`을 internal compatibility로 유지하고, compose host publish 기본값을 `18010:8080`으로 맞춘다. 기존 `8080` host publish가 필요하면 `NOMADCODE_CORE_HOST_PORT=8080` override로 확인한다. +- [x] [infra-ports] PostgreSQL/Redis는 현재 compose 내부에서 `code-server-postgres:5432`, `code-server-redis:6379` service DNS를 사용하고 별도 host publish를 갖지 않는다. 필요한 경우만 DB/cache offset 대역 `15410/16310` 노출 후보를 문서화한다. +- [x] [external-endpoints] IOP Edge OpenAI-compatible endpoint는 현재 `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC`로 설정하고, A2A/proto-socket/provider 연동은 `A2A_*`, `PROTO_SOCKET_*`, `PLANE_*`, `JIRA_*`, `MATTERMOST_*` env로 분리한다. raw secret 없이 source of truth와 책임 경계만 남긴다. ## 완료 리뷰 -- 상태: 없음 -- 요청일: 없음 -- 완료 근거: 없음 +- 상태: 요청됨 +- 요청일: 2026-06-07 +- 완료 근거: + - `README.md`, `services/core/README.md`, `apps/client/README.md`, `agent-test/local/mobile-smoke.md`, `packages/contracts/notes/flutter-core-api-candidates.md`에 workspace 포트 대역과 compatibility baseline을 문서화했다. + - Flutter preview `13010+`, Core host publish `18010:8080`, PostgreSQL/Redis host publish 후보 `15410/16310`, IOP/provider env group의 secret-free 책임 경계를 분리했다. + - `agent-test/local/*`의 기본 host를 standard remote runner 기준으로 정리하고 Android/Mattermost remote smoke의 포트 기준을 채웠다. + - Core compose host publish 기본값을 `18010:8080`으로 바꾸고, 기존 `8080` host publish는 `NOMADCODE_CORE_HOST_PORT=8080` override로 남겼다. + - 검증: `git diff --check` PASS. + - 검증: standard remote runner에서 `zsh -lc 'docker compose ... config'`로 compose 렌더링을 확인했다. 기본 publish는 `published: "18010"`, `NOMADCODE_CORE_HOST_PORT=8080` override는 `published: "8080"`으로 확인했다. - 리뷰 필요: - [ ] 사용자가 완료 결과를 확인했다 - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 없음 +- 리뷰 코멘트: 작은 문서화 작업은 바로 처리했으며, 별도 large plan 대상은 남기지 않았다. ## 범위 제외 @@ -62,8 +68,8 @@ NomadCode가 직접 소유한 client/core 포트와 외부 IOP/Nexo/Plane 연동 - 표준선(선택): container 내부 포트와 기존 local default는 compatibility baseline으로 유지하고, host publish, preview, remote runner 문서부터 workspace 대역으로 정렬한다. - 현재 작업 동기화: - 활성 로드맵 포인터는 `Agent-Ops MCP Control Plane` Phase와 이 Milestone을 가리키며, active `agent-task/` 작업 파일은 없다. - - Core baseline source는 `services/core/internal/config/config.go`, `services/core/Makefile`, `services/core/docker-compose.yml`, `services/core/Dockerfile`, `services/core/README.md`에 흩어져 있고, 현재 외부 host publish 기준은 `8080`이다. - - Client preview baseline source는 `agent-test/local/mobile-smoke.md`이며, 현재 human web preview는 code-server `/proxy//`와 예시 `8081`을 사용한다. + - Core baseline source는 `services/core/internal/config/config.go`, `services/core/Makefile`, `services/core/docker-compose.yml`, `services/core/Dockerfile`, `services/core/README.md`에 흩어져 있고, internal compatibility port는 `8080`, compose host publish 기본값은 `18010`이다. + - Client preview baseline source는 `agent-test/local/mobile-smoke.md`이며, human web preview는 code-server `/proxy//`와 기본 `13010+`, legacy/ad hoc `8081` 호환을 함께 사용한다. - Workspace mock entry는 `apps/client/lib/src/features/workspaces/domain/project_workspace.dart`에서 code-server `localhost:8080` URL을 사용한다. - Proto-socket client endpoint는 `apps/client/lib/src/integrations/proto_socket/proto_socket_endpoint_config.dart`의 `PROTO_SOCKET_*` env에서 오며, host가 없으면 비활성화된다. - external provider/model endpoint 값은 tracked roadmap에 실제 token/password를 기록하지 않고 env 이름과 책임 경계만 동기화한다. diff --git a/apps/client/README.md b/apps/client/README.md index e7fc23d..8a12037 100644 --- a/apps/client/README.md +++ b/apps/client/README.md @@ -55,6 +55,14 @@ For detailed integration boundaries, platform targets, and clone handoff guideli --- +## Web Preview Ports + +Human Flutter web preview through code-server should use the `/proxy//` base href. For stable workspace previews, prefer `13010` and then `13011`, `13012`, and so on for parallel previews. Existing ad hoc local smoke flows that use a fresh port such as `8081` remain valid compatibility checks. + +The mock workspace `codeServerUrl` values that point at `http://localhost:8080/?folder=...` are code-server workspace entry links, not Flutter web preview ports. Keep them separate from the `13010+` preview band. + +--- + ## Mattermost Push Notification Integration Mattermost push notification delivery is implemented via the local `nexo_messaging` path dependency at `../nexo/packages/messaging_flutter`. diff --git a/packages/contracts/notes/flutter-core-api-candidates.md b/packages/contracts/notes/flutter-core-api-candidates.md index d49150d..80dea8f 100644 --- a/packages/contracts/notes/flutter-core-api-candidates.md +++ b/packages/contracts/notes/flutter-core-api-candidates.md @@ -88,6 +88,19 @@ - **Wire message**: 초기 구현은 `google.protobuf.Struct` semantic envelope를 사용한다. - **Heartbeat**: proto-socket 기본 heartbeat를 사용하며 Core 설정 기본값은 interval 30s, wait 10s다. +### 1.4.1 Workspace port와 endpoint compatibility 후보 +- **설명**: 이 표는 source schema가 아니라 NomadCode workspace/remote runner에서 core, Flutter preview, provider endpoint를 같은 언어로 다루기 위한 compatibility note다. + +| 표면 | 후보 기준 | compatibility note | +|------|-----------|--------------------| +| Flutter web preview | code-server `/proxy//` 아래 `13010+` host port 대역 | 기존 local smoke의 ad hoc `8081` 계열 포트는 계속 허용한다. | +| code-server workspace entry | `http://localhost:8080/?folder=...` mock URL 유지 | 이 URL은 code-server entry 호환성이고 Flutter web preview 포트가 아니다. | +| Core HTTP/API | process/container 내부 `8080`, workspace host publish 기본값 `18010:8080` | `HTTP_ADDR=:8080`, Docker `EXPOSE 8080`, local curl `localhost:8080`은 migration compatibility로 유지하고, compose는 `NOMADCODE_CORE_HOST_PORT`로 host port를 override한다. | +| PostgreSQL | compose/service DNS `code-server-postgres:5432`; host 필요 시 `15410:5432` 후보 | 기본 내부 통신은 service DNS를 우선하고 host publish는 추가하지 않는다. | +| Redis | compose/service DNS `code-server-redis:6379`; host 필요 시 `16310:6379` 후보 | 기본 내부 통신은 service DNS를 우선하고 host publish는 추가하지 않는다. | +| proto-socket client/core endpoint | client는 `PROTO_SOCKET_*`, core는 `/proto-socket`과 heartbeat env를 사용 | client `PROTO_SOCKET_HOST`가 없으면 connector는 비활성화된다. | +| IOP Edge/provider endpoints | `MODEL_*`, `A2A_*`, `PLANE_*`, `JIRA_*`, `MATTERMOST_*` env group | raw token, password, API key 값은 tracked contract note에 기록하지 않는다. | + ### 1.5 Task Channel Actions (구현됨) - **설명**: `services/core/internal/protosocket`가 REST task API와 같은 의미를 `task` channel의 proto-socket action으로 제공한다. REST는 smoke/compat로 유지한다. - **안정성 수준**: 후보 (Candidate) diff --git a/services/core/README.md b/services/core/README.md index aec99b4..b3a0dec 100644 --- a/services/core/README.md +++ b/services/core/README.md @@ -38,6 +38,14 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 모델 호출의 기본 방향은 IOP Edge의 OpenAI-compatible Responses input surface입니다. `MODEL_BASE_URL`은 IOP Edge listener를 가리키고, 해당 listener는 non-streaming `POST /v1/responses`를 제공해야 합니다. NomadCode는 OpenAI-compatible request/response shape를 기본 계약으로 유지하고, task/workspace/session/approval/artifact/notification 같은 IOP/NomadCode 전용 실행 문맥은 별도 `iop` wrapper field가 아니라 요청 `metadata` 확장으로 전달하는 방향을 기준으로 합니다. 현재 코드와 local script에는 개발 호환용 direct model endpoint/Ollama 기본값이 남아 있을 수 있지만, 로드맵과 운영 기준의 기본 실행 경로는 IOP 경유 호출입니다. A2A agent 호출 endpoint는 `A2A_EDGE_URL`로 설정하고, 기존 `A2A_AGENT_URL`도 fallback alias로 받습니다. bearer token은 `A2A_TOKEN`, timeout은 `A2A_TIMEOUT_SEC`로 설정합니다. A2A는 향후 외부 agent delegation 표면이며 현재 기본 실행 경로는 아닙니다. Plane 연동은 `PLANE_BASE_URL`, `PLANE_TOKEN`으로 설정하며, toki-labs dev Plane 기본 URL은 `https://plane.toki-labs.com` 입니다. +### 포트와 환경 compatibility + +Core process와 container 내부 포트는 `8080`을 compatibility baseline으로 유지합니다. `Makefile`, `bin/run`, `internal/config`의 local default는 `HTTP_ADDR=:8080`이고, `Dockerfile`도 `EXPOSE 8080`을 유지합니다. shared workspace나 remote runner에서 host publish가 필요할 때 compose 기본값은 container 내부 포트를 그대로 두고 host 쪽을 `18010:8080`으로 노출합니다. 기존 `localhost:8080` curl 예시는 local 단독 실행 compatibility 확인용으로 남기며, compose host publish를 예전처럼 써야 하면 `NOMADCODE_CORE_HOST_PORT=8080`을 지정합니다. + +PostgreSQL과 Redis는 기본적으로 `code-server-postgres:5432`, `code-server-redis:6379` service DNS로 접근합니다. compose 내부 통신에는 host publish를 추가하지 않습니다. 운영상 host에서 직접 접근해야 하는 경우에만 PostgreSQL은 `15410:5432`, Redis는 `16310:6379` 대역 후보를 사용합니다. + +외부 endpoint와 secret은 포트 표준과 분리합니다. IOP Edge OpenAI-compatible listener는 `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC`로 설정하고, A2A는 `A2A_EDGE_URL`/`A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC`로 분리합니다. Core proto-socket endpoint는 `PROTO_SOCKET_PATH`, `PROTO_SOCKET_HEARTBEAT_INTERVAL_SEC`, `PROTO_SOCKET_HEARTBEAT_WAIT_SEC`로 조정하고, Flutter client connector는 `PROTO_SOCKET_HOST`, `PROTO_SOCKET_PORT`, `PROTO_SOCKET_SECURE`, `PROTO_SOCKET_ENABLED`, `PROTO_SOCKET_PATH`, `PROTO_SOCKET_HEARTBEAT_INTERVAL_SECONDS`, `PROTO_SOCKET_HEARTBEAT_WAIT_SECONDS`를 사용합니다. Plane, Jira, Mattermost 값은 각각 `PLANE_*`, `JIRA_*`, `MATTERMOST_*` env로 주입하며 token/API key 원문은 tracked 문서에 기록하지 않습니다. + `code-server` PostgreSQL 컨테이너에 DB를 생성하는 예시: ```bash @@ -170,6 +178,12 @@ Docker Compose 실행은 dev 배포용입니다. compose는 외부 Docker 네트 AUTH_PASSWORD="change-me" ./bin/docker-up ``` +Compose의 기본 host publish는 remote/local test workspace 기준 `18010:8080`입니다. 기존 host `8080`이 필요한 호환성 확인에서는 아래처럼 명시합니다. + +```bash +NOMADCODE_CORE_HOST_PORT=8080 AUTH_PASSWORD="change-me" ./bin/docker-up +``` + Makefile은 같은 명령을 감싸는 얇은 alias입니다. ```bash diff --git a/services/core/docker-compose.yml b/services/core/docker-compose.yml index 4f5519a..c4333a5 100644 --- a/services/core/docker-compose.yml +++ b/services/core/docker-compose.yml @@ -25,7 +25,7 @@ services: PLANE_BASE_URL: ${PLANE_BASE_URL:-} PLANE_TOKEN: ${PLANE_TOKEN:-} ports: - - "8080:8080" + - "${NOMADCODE_CORE_HOST_PORT:-18010}:8080" networks: - net_nginx