toki/nexo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: remote compose 설정 업데이트 및 문서 동기화

Browse source 
- runtime-image-validation.md 문서 개선
- compose .env.example 및 README 업데이트
- docker-compose.yml 설정 개선
- G07 관련 하위 파일 정리
This commit is contained in:
toki 2026-05-28 10:53:13 +09:00
parent 6ca7989169
commit 1eeed5218f
6 changed files with 56 additions and 270 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
agent-task/m-runtime-image-validation/02+01_remote_compose/CODE_REVIEW-cloud-G07.md
View file

@ -1,112 +0,0 @@
<!-- task=m-runtime-image-validation/02+01_remote_compose plan=0 tag=REMOTE -->
# Code Review Reference - REMOTE
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
## 개요
date=2026-05-28
task=m-runtime-image-validation/02+01_remote_compose, plan=0, tag=REMOTE
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [REMOTE-1] local compose image defaults | [ ] |
| [REMOTE-2] remote compose sync and smoke | [ ] |
## 구현 체크리스트
- [ ] [REMOTE-1] local compose를 nexo-owned `latest` image와 Mac 전용 `linux/arm64` platform 기준으로 전환한다.
- [ ] [REMOTE-2] local compose 변경을 원격 `~/docker/services/nexo/compose`에 반영하고 pull/up/smoke evidence를 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [ ] active `CODE_REVIEW-cloud-G07.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
- [ ] active `PLAN-cloud-G07.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-runtime-image-validation/02+01_remote_compose/`로 이동한다.
- [ ] PASS split 작업이면 이동 후 빈 active parent 상태를 확인한다.
- [ ] WARN/FAIL이면 다음 active plan/review 또는 `USER_REVIEW.md`를 작성하고 `complete.log`를 작성하지 않는다.
## 계획 대비 변경 사항
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
## 주요 설계 결정
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- `docker-compose.yml` 기본 image가 `toki-labs.com:5050/nexo/*:latest`이고 platform이 `linux/arm64`인지 확인한다.
- README가 `latest` stable pointer와 `docker compose pull && docker compose up -d` 운영을 설명하는지 확인한다.
- remote smoke 출력이 실제 원격 명령 결과인지 확인한다.
## 검증 결과
### REMOTE-1 중간 검증
```sh
$ cd services/core/compose
$ rg --sort path -n "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64|NEXO_.*IMAGE" docker-compose.yml .env.example README.md
(output)
```
### REMOTE-2 중간 검증
```sh
$ cd services/core/compose
$ sha256sum docker-compose.yml .env.example
(output)
$ ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example && /usr/local/bin/docker compose --env-file .env.example config >/tmp/nexo-compose-config.yml && /usr/bin/grep -E "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64" /tmp/nexo-compose-config.yml'
(output)
$ ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && /usr/local/bin/docker compose pull && /usr/local/bin/docker compose up -d && curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" && /usr/local/bin/docker compose exec -T db pg_isready -U mmuser -d mattermost && curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" && /usr/local/bin/docker compose ps push-proxy'
(output)
```
### 최종 검증
```sh
$ test -f agent-task/m-runtime-image-validation/01_image_publish/complete.log
(output)
$ cd services/core/compose
$ rg --sort path -n "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64|NEXO_.*IMAGE" docker-compose.yml .env.example README.md
(output)
$ sha256sum docker-compose.yml .env.example
(output)
$ ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example && /usr/local/bin/docker compose --env-file .env.example config >/tmp/nexo-compose-config.yml && /usr/bin/grep -E "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64" /tmp/nexo-compose-config.yml'
(output)
$ ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && /usr/local/bin/docker compose pull && /usr/local/bin/docker compose up -d && curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" && /usr/local/bin/docker compose exec -T db pg_isready -U mmuser -d mattermost && curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" && /usr/local/bin/docker compose ps push-proxy'
(output)
```
## 코드리뷰 결과
_리뷰 에이전트가 append한다._

155
agent-task/m-runtime-image-validation/02+01_remote_compose/PLAN-cloud-G07.md
View file

@ -1,155 +0,0 @@
<!-- task=m-runtime-image-validation/02+01_remote_compose plan=0 tag=REMOTE -->
# Plan - REMOTE
## 이 파일을 읽는 구현 에이전트에게
이 task는 `agent-task/m-runtime-image-validation/01_image_publish/complete.log`가 있어야 시작한다. `CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 외부 환경이나 사용자 결정으로 막히면 review stub의 `사용자 리뷰 요청`을 채우고 중단한다.
## 배경
core/push-proxy image가 nexo-owned registry로 publish되면 local/remote compose가 그 image를 소비해야 한다. 현재 local과 remote compose는 upstream amd64 core image와 upstream latest push-proxy image를 직접 참조한다.
## 사용자 리뷰 요청 흐름
구현 중 차단 사항은 active `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 요청을 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.
## 분석 결과
### 읽은 파일
- `agent-roadmap/current.md`
- `agent-roadmap/phase/product-foundation/PHASE.md`
- `agent-roadmap/phase/product-foundation/milestones/runtime-image-validation.md`
- `agent-ops/rules/project/domain/workspace-ops/rules.md`
- `agent-ops/rules/project/domain/core-service/rules.md`
- `services/core/compose/docker-compose.yml`
- `services/core/compose/.env.example`
- `services/core/compose/README.md`
- `services/core/UPSTREAM.md`
- `bin/test`
- `bin/lint`
- `bin/build`
- 원격 `~/docker/services/nexo/compose/docker-compose.yml`
### 테스트 커버리지 공백
- compose image/platform 변경은 unit test가 없다. 검증은 `docker compose config`, registry pull, remote `docker compose up -d`, HTTP/db/push-proxy smoke로 한다.
- remote parity는 README에 hash 비교가 있지만 자동화되어 있지 않다.
### 심볼 참조
- none. 심볼 rename/remove 작업이 아니다.
### 분할 판단
Split policy를 평가했고 이 task는 `02+01_remote_compose`로 둔다. 01의 image publish evidence 없이는 compose를 바꾸면 pull 실패가 나므로 `01_image_publish`에 의존한다. repo/consumer e2e는 다른 검증 경계라 `03+02_validation_matrix`로 분리한다.
### 범위 결정 근거
- 이 task는 `services/core/compose`와 원격 `~/docker/services/nexo/compose`만 다룬다.
- `services/core/server/`, `services/push-proxy/` source, consumer project 파일은 수정하지 않는다.
- registry auth, production hardening, multi-arch/amd64는 제외한다.
### 빌드 등급
- build=`cloud-G07`, review=`cloud-G07`. SSH, Docker Compose, 원격 smoke 출력이 성공 조건인 terminal-agent 작업이다.
## 구현 체크리스트
- [ ] [REMOTE-1] local compose를 nexo-owned `latest` image와 Mac 전용 `linux/arm64` platform 기준으로 전환한다.
- [ ] [REMOTE-2] local compose 변경을 원격 `~/docker/services/nexo/compose`에 반영하고 pull/up/smoke evidence를 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 의존 관계 및 구현 순서
- 선행 subtask: `01_image_publish`.
- 시작 전 `test -f agent-task/m-runtime-image-validation/01_image_publish/complete.log`를 확인한다.
### [REMOTE-1] Local Compose Image Defaults
문제: `services/core/compose/docker-compose.yml:27-28`은 upstream `mattermost/mattermost-team-edition:11.4.2`와 `linux/amd64`를 사용한다. `:58`은 upstream `mattermost/mattermost-push-proxy:latest`를 사용한다.
해결 방법:
Before:
```yaml
27: image: mattermost/mattermost-team-edition:11.4.2
28: platform: linux/amd64
58: image: mattermost/mattermost-push-proxy:latest
```
After:
```yaml
image: ${NEXO_CORE_IMAGE:-toki-labs.com:5050/nexo/mattermost:latest}
platform: linux/arm64
image: ${NEXO_PUSH_PROXY_IMAGE:-toki-labs.com:5050/nexo/push-proxy:latest}
```
`.env.example`에 `NEXO_CORE_IMAGE`와 `NEXO_PUSH_PROXY_IMAGE` 기본값을 추가한다. README에는 `latest`가 검증 완료 stable pointer이며 배포 시 `docker compose pull && docker compose up -d`를 실행해야 한다고 적는다.
수정 파일 및 체크리스트:
- [ ] `services/core/compose/docker-compose.yml`
- [ ] `services/core/compose/.env.example`
- [ ] `services/core/compose/README.md`
테스트 작성: compose 설정 변경은 별도 test file을 추가하지 않는다. `docker compose config`와 remote smoke가 검증이다.
중간 검증:
```sh
cd services/core/compose
rg --sort path -n "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64|NEXO_.*IMAGE" docker-compose.yml .env.example README.md
```
기대 결과: local compose inputs에 image/platform/env var가 모두 나타난다. 실제 compose config 검증은 원격 Docker CLI로 수행한다.
### [REMOTE-2] Remote Compose Sync And Smoke
문제: README는 local/remote parity를 요구하지만, 원격 compose는 아직 upstream amd64/latest image를 쓴다. nexo-owned image로 전환한 뒤 pull/up/smoke evidence가 필요하다.
해결 방법: local compose 파일과 `.env.example`을 원격 `~/docker/services/nexo/compose`에 복사한다. 원격에서 `docker compose pull`, `docker compose up -d`, core ping, Mattermost HEAD, db readiness, push-proxy service 상태, image inspect를 실행한다. remote drift가 의도적이지 않도록 sha256sum을 기록한다.
수정 파일 및 체크리스트:
- [ ] 원격 `~/docker/services/nexo/compose/docker-compose.yml`
- [ ] 원격 `~/docker/services/nexo/compose/.env.example`
- [ ] `docs/runtime-image-validation.md`에 remote compose smoke evidence를 추가한다.
테스트 작성: 원격 runtime smoke가 acceptance test다. 자동 test file은 추가하지 않는다.
중간 검증:
```sh
cd services/core/compose
sha256sum docker-compose.yml .env.example
ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example && /usr/local/bin/docker compose --env-file .env.example config >/tmp/nexo-compose-config.yml && /usr/bin/grep -E "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64" /tmp/nexo-compose-config.yml'
ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && /usr/local/bin/docker compose pull && /usr/local/bin/docker compose up -d && curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" && /usr/local/bin/docker compose exec -T db pg_isready -U mmuser -d mattermost && curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" && /usr/local/bin/docker compose ps push-proxy'
```
기대 결과: local/remote hash가 일치하고, 원격 compose가 nexo-owned latest image를 사용하며 smoke 명령이 성공한다.
## 수정 파일 요약
| 파일 | 항목 |
|------|------|
| `services/core/compose/docker-compose.yml` | REMOTE-1 |
| `services/core/compose/.env.example` | REMOTE-1 |
| `services/core/compose/README.md` | REMOTE-1 |
| `docs/runtime-image-validation.md` | REMOTE-2 |
| 원격 `~/docker/services/nexo/compose/docker-compose.yml` | REMOTE-2 |
| 원격 `~/docker/services/nexo/compose/.env.example` | REMOTE-2 |
## 최종 검증
```sh
test -f agent-task/m-runtime-image-validation/01_image_publish/complete.log
cd services/core/compose
rg --sort path -n "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64|NEXO_.*IMAGE" docker-compose.yml .env.example README.md
sha256sum docker-compose.yml .env.example
ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example && /usr/local/bin/docker compose --env-file .env.example config >/tmp/nexo-compose-config.yml && /usr/bin/grep -E "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64" /tmp/nexo-compose-config.yml'
ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && /usr/local/bin/docker compose pull && /usr/local/bin/docker compose up -d && curl -fsS "http://localhost:${NEXO_CORE_PORT:-18065}/api/v4/system/ping" && /usr/local/bin/docker compose exec -T db pg_isready -U mmuser -d mattermost && curl -fsSI "http://localhost:${NEXO_CORE_PORT:-18065}" && /usr/local/bin/docker compose ps push-proxy'
```
모든 명령은 fresh 실행이어야 하며 cached output은 허용하지 않는다. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

47
docs/runtime-image-validation.md
View file

@ -45,3 +45,50 @@ linux/arm64 toki-labs.com:5050/nexo/mattermost@sha256:a811233f0625dd72a43c4b2315
linux/arm64 toki-labs.com:5050/nexo/push-proxy@sha256:73d104148e66bb24e901bd1787624cf9b46e41268955e20bdfe4c6fc70f10b0b
linux/arm64 toki-labs.com:5050/nexo/push-proxy@sha256:73d104148e66bb24e901bd1787624cf9b46e41268955e20bdfe4c6fc70f10b0b
```
### Remote Compose Smoke Evidence
This section contains the validation log of copying the local compose files to the remote development host, running a config check, pulling nexo-owned images, and performing service smoke tests.
```sh
# 1. Compare local and remote file hashes (Parity Verification)
$ sha256sum docker-compose.yml .env.example
c46bc291e42b1e87ca5e6b49d118bb59c67b0b2b1412a2751c6089e49d492563 docker-compose.yml
fa56a8dc7a8dddc7737d42ec048e4f29836252e277e2d270f0ad0e7cbb38d430 .env.example
$ ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && sha256sum docker-compose.yml .env.example'
c46bc291e42b1e87ca5e6b49d118bb59c67b0b2b1412a2751c6089e49d492563 docker-compose.yml
fa56a8dc7a8dddc7737d42ec048e4f29836252e277e2d270f0ad0e7cbb38d430 .env.example
# 2. Check remote Docker Compose configuration
$ ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && /usr/local/bin/docker compose --env-file .env.example config >/tmp/nexo-compose-config.yml && /usr/bin/grep -E "toki-labs.com:5050/nexo/(mattermost|push-proxy):latest|platform: linux/arm64" /tmp/nexo-compose-config.yml'
image: toki-labs.com:5050/nexo/mattermost:latest
platform: linux/arm64
image: toki-labs.com:5050/nexo/push-proxy:latest
# 3. Pull and start services on the remote server
$ ssh toki@toki-labs.com 'export PATH=$PATH:/Applications/Docker.app/Contents/Resources/bin && cd ~/docker/services/nexo/compose && /usr/local/bin/docker compose pull && /usr/local/bin/docker compose up -d'
Container nexo-core-db Running
Container nexo-core-push-proxy Recreated
Container nexo-core Recreated
Container nexo-core-push-proxy Started
Container nexo-core-db Healthy
Container nexo-core Started
# 4. Remote Runtime Smoke Checks
$ ssh toki@toki-labs.com 'cd ~/docker/services/nexo/compose && curl -fsS "http://localhost:18065/api/v4/system/ping" && /usr/local/bin/docker compose exec -T db pg_isready -U mmuser -d mattermost && curl -fsSI "http://localhost:18065" && /usr/local/bin/docker compose ps push-proxy'
{"ActiveSearchBackend":"database","AndroidLatestVersion":"","AndroidMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}
/var/run/postgresql:5432 - accepting connections
HTTP/1.1 200 OK
Cache-Control: no-cache, max-age=31556926, public
Content-Security-Policy: frame-ancestors 'self' ; script-src 'self'
Content-Type: text/html
Permissions-Policy:
Referrer-Policy: no-referrer
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-Request-Id: 1z4r5bc67b89fd8x816dexgsse
X-Version-Id: 11.4.2.22416167438.bfd0f10f265c336e8b5a043b0dccdcd64438e08f73bcc5627b72c815906e1130.false
Date: Thu, 28 May 2026 01:41:27 GMT
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
nexo-core-push-proxy toki-labs.com:5050/nexo/push-proxy:latest "/usr/local/b..." push-proxy 3 seconds ago Up 2 seconds 0.0.0.0:18066->8066/tcp
```

2
services/core/compose/.env.example
View file

@ -2,3 +2,5 @@ NEXO_DB_PASSWORD=mmuser_password
NEXO_SITE_URL=http://localhost:18065
NEXO_CORE_PORT=18065
NEXO_PUSH_PROXY_PORT=18066
NEXO_CORE_IMAGE=toki-labs.com:5050/nexo/mattermost:latest
NEXO_PUSH_PROXY_IMAGE=toki-labs.com:5050/nexo/push-proxy:latest

4
services/core/compose/README.md
View file

@ -8,9 +8,13 @@ This compose file mirrors the current Mattermost-based runtime shape inside the
```sh
cd services/core/compose
cp -n .env.example .env
docker compose pull
docker compose up -d
```
`latest` is the verified stable pointer for nexo-owned runtime images.
When running or updating, you should run `docker compose pull && docker compose up -d` to fetch the latest stable images.
Runtime state is written to `services/core/data/`, which is ignored by git.
Place push-proxy configuration under
`services/core/data/push-proxy/config/mattermost-push-proxy.json` when FCM smoke

6
services/core/compose/docker-compose.yml
View file

@ -24,8 +24,8 @@ services:
max-file: "3"
core:
image: mattermost/mattermost-team-edition:11.4.2
platform: linux/amd64
image: ${NEXO_CORE_IMAGE:-toki-labs.com:5050/nexo/mattermost:latest}
platform: linux/arm64
container_name: nexo-core
restart: unless-stopped
depends_on:
@ -55,7 +55,7 @@ services:
max-file: "5"
push-proxy:
image: mattermost/mattermost-push-proxy:latest
image: ${NEXO_PUSH_PROXY_IMAGE:-toki-labs.com:5050/nexo/push-proxy:latest}
container_name: nexo-core-push-proxy
restart: unless-stopped
environment: