nexo/agent-task/m-runtime-baseline/02_runtime_smoke/PLAN-cloud-G07.md

Plan - Runtime Smoke And Remote Parity

이 파일을 읽는 구현 에이전트에게

구현이 끝나면 반드시 CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 검증 명령을 실행하고 실제 stdout/stderr를 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 최종 archive, complete.log, 코드리뷰 판정은 code-review 스킬 전용이다.

배경

현재 compose 문서는 core, db, push-proxy를 올리는 방법과 smoke 절차를 갖췄지만 실제 Docker 기동과 원격 hash parity는 아직 완료 evidence가 없다. 이 작업은 Docker-capable 환경과 remote host 접근이 필요한 실행 검증이다. smoke 실패가 compose 설정 문제로 확인될 때만 repo 파일을 최소 수정한다.

분석 결과

읽은 파일

• agent-roadmap/current.md
• agent-roadmap/phase/product-foundation/PHASE.md
• agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md
• README.md
• docs/README.md
• services/core/compose/README.md
• services/core/compose/.env.example
• services/core/compose/docker-compose.yml
• .gitignore

테스트 커버리지 공백

• local-compose: 기존 자동 테스트 없음. 실제 docker compose up -d, core ping, app HEAD, db readiness, push-proxy service/config check 출력이 evidence다.
• remote-parity: 기존 자동 테스트 없음. local/remote sha256sum 출력 일치와 원격 smoke 출력이 evidence다.
• compose 수정이 발생하는 경우: unit test는 없고 docker compose config, smoke command, git diff --check로 검증한다.

심볼 참조

none. 이 작업은 code symbol rename/remove를 하지 않는다.

분할 판단

split decision policy를 먼저 평가했다. shared task group은 m-runtime-baseline이다.

• 01_source_snapshots: upstream source snapshot 반입. 외부 git snapshot 리스크.
• 02_runtime_smoke: Docker/SSH smoke 검증. terminal-agent 리스크.

두 sibling 사이에 런타임 선행 의존성은 없다. 이 plan 내부에서는 local smoke 후 remote parity를 진행한다.

범위 결정 근거

이 작업은 services/core/compose/docker-compose.yml, services/core/compose/.env.example, services/core/compose/README.md, 그리고 원격 ~/docker/services/nexo/compose parity 확인만 다룬다. nginx/TLS, production hardening, push credential validation, push-proxy source build 전환, 기존 다른 compose 서비스와의 병합은 범위 밖이다. 계획 작성 환경에서는 command -v docker가 빈 출력이었으므로 실제 완료는 Docker 사용 가능한 환경에서만 가능하다.

빌드 등급

build=cloud-G07, review=cloud-G07. Docker/SSH/long-running service smoke와 stdout/stderr evidence가 핵심인 terminal-agent 작업이다.

구현 체크리스트

• command -v docker, docker compose version, docker info로 Docker 실행 가능성을 확인한다.
• services/core/compose에서 .env를 git 밖에 준비하고 docker compose config가 성공하는지 확인한다.
• docker compose up -d 후 core ping, Mattermost app HEAD, db readiness, push-proxy service/config smoke를 실행한다. 검증: cd services/core/compose && docker compose up -d 후 core ping과 Mattermost 앱 접근이 성공한다.
• NEXO_REMOTE_HOST를 사용해 원격 ~/docker/services/nexo/compose의 docker-compose.yml과 .env.example hash가 local과 일치하는지 확인한다. 검증: local/remote compose와 .env.example hash 비교가 일치한다.
• smoke 실패가 repo 설정 문제로 확인될 때만 compose 파일이나 README를 최소 수정하고 같은 smoke를 재실행한다.
• CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

[SMOKE-1] Local Compose Runtime

문제

Milestone의 [local-compose]는 agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md:53에서 미완료이고 실제 Docker 기동 evidence가 필요하다. services/core/compose/docker-compose.yml:16부터 db healthcheck가 있고 services/core/compose/docker-compose.yml:47은 core가 push-proxy를 compose DNS로 참조하지만, runtime smoke 출력은 아직 없다.

해결 방법

Docker-capable 환경에서 local compose를 detached mode로 올리고 README에 기록된 smoke를 실행한다. .env는 services/core/compose/.env.example:1부터 services/core/compose/.env.example:4를 복사해 만들되 git에 올리지 않는다.

cd services/core/compose
cp -n .env.example .env
docker compose config
docker compose up -d
curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"
docker compose exec db pg_isready -U mmuser -d mattermost
curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}"
docker compose ps push-proxy
docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066"

실패 원인이 repo 설정이면 docker-compose.yml, .env.example, README.md 중 필요한 파일만 수정한다. Docker daemon 부재, port collision, missing remote secret처럼 repo 밖 문제면 수정하지 말고 blocker로 기록한다.

수정 파일 및 체크리스트

• 필요 시 services/core/compose/docker-compose.yml을 최소 수정한다.
• 필요 시 services/core/compose/.env.example을 최소 수정한다.
• 필요 시 services/core/compose/README.md를 실제 smoke와 맞춘다.
• .env와 services/core/data/는 git에 포함하지 않는다.

테스트 작성

테스트 파일은 작성하지 않는다. 이 항목은 runtime smoke이며 실제 Docker command 출력이 검증이다.

중간 검증

cd services/core/compose
command -v docker
docker compose version
docker info
docker compose config
docker compose up -d
curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"
docker compose exec db pg_isready -U mmuser -d mattermost
curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}"
docker compose ps push-proxy
docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066"

[SMOKE-2] Remote Parity

문제

Milestone의 [remote-parity]는 agent-roadmap/phase/product-foundation/milestones/runtime-baseline.md:54에서 미완료다. services/core/compose/README.md:58부터 hash 비교 절차가 있지만 실제 remote output이 없다.

해결 방법

원격 host를 NEXO_REMOTE_HOST로 받고 local/remote hash를 비교한다. 원격 파일이 의도한 배포 copy와 다르면 원격을 동기화한 뒤 같은 명령을 재실행한다. repo 파일은 local source of truth가 틀린 경우에만 수정한다.

test -n "$NEXO_REMOTE_HOST"
cd services/core/compose
sha256sum docker-compose.yml .env.example
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example'

hash가 일치하면 원격에서도 최소 smoke를 실행한다. 원격 .env와 runtime data는 git 밖에 있어야 한다.

ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config'
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps'
ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"'

수정 파일 및 체크리스트

• local/remote hash output을 기록한다.
• 원격 drift가 있으면 원격 sync 또는 의도적 drift 사유를 기록한다.
• repo 문서가 실제 remote 기준과 다를 때만 services/core/compose/README.md를 수정한다.

테스트 작성

테스트 파일은 작성하지 않는다. 이 항목은 remote smoke이며 SSH command 출력이 검증이다.

중간 검증

test -n "$NEXO_REMOTE_HOST"
cd services/core/compose
sha256sum docker-compose.yml .env.example
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example'
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config'
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps'
ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"'

의존 관계 및 구현 순서

1. SMOKE-1 local compose smoke를 먼저 수행한다.
2. SMOKE-2 remote parity와 remote smoke를 수행한다.
3. 둘 중 repo 설정 문제가 발견된 경우에만 최소 수정 후 해당 smoke부터 재실행한다.

수정 파일 요약

파일	항목
services/core/compose/docker-compose.yml	SMOKE-1
services/core/compose/.env.example	SMOKE-1
services/core/compose/README.md	SMOKE-1, SMOKE-2

최종 검증

cd services/core/compose
command -v docker
docker compose version
docker info
docker compose config
docker compose up -d
curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"
docker compose exec db pg_isready -U mmuser -d mattermost
curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}"
docker compose ps push-proxy
docker compose config | rg --fixed-strings "MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=http://push-proxy:8066"
test -n "$NEXO_REMOTE_HOST"
sha256sum docker-compose.yml .env.example
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example'
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose config'
ssh "$NEXO_REMOTE_HOST" 'cd ~/docker/services/nexo/compose && docker compose ps'
ssh "$NEXO_REMOTE_HOST" 'curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping"'
cd ../../..
git status --short services/core/compose
git diff --check

Expected outcome: Docker is available, compose config is valid, local core ping and app HEAD succeed, db is ready, push-proxy service/config smoke succeeds, remote hashes match local hashes, remote compose config and ping succeed, and git diff --check reports no whitespace errors.

모든 코드 변경 완료 후 반드시 CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.