toki
0d83ef378e
사용자가 artifact URL, Edge 주소, token을 환경변수로 직접 설정하던 IOP_* named parameter 방식을 제거하고, curl | bash -s <token> 형태의 단일 positional token UX로 변경한다. - bootstrap script에서 NODE_TOKEN을 첫 번째 인자로 받도록 변경 - token 누락 시 명확한 에러 메시지 출력 - artifact HTTP를 127.0.0.1 바인딩으로 변경 - docs, rules, roadmap에 one-line bootstrap UX 기준 기록
89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
# Field Bootstrap 작업 가이드
|
|
|
|
이 문서는 작업자/LLM이 field bootstrap 테스트를 이어갈 때 읽는 재개 가이드다.
|
|
사용자에게 그대로 전달하는 문서는 `docs/field-bootstrap-user-test.md`를 사용하고, 상세 runbook은 `docs/deploy-dev.md`를 확인한다.
|
|
|
|
## 핵심 규칙
|
|
|
|
- Edge-Node 런타임 연결에 외부 공개가 필요한 포트는 `19090` 하나다.
|
|
- `18080`은 bootstrap shell script, `iop-node` binary, checksum을 내려받는 artifact HTTP 포트다. Edge-Node 런타임 포트가 아니다.
|
|
- 외부 공개를 `19090` 하나로 제한할 때는 `toki-labs.com:18080`을 사용자 기본 명령으로 안내하지 않는다.
|
|
- bootstrap/artifact는 내부망, front/control-plane, CI artifact, 또는 임시 로컬 HTTP 등 별도 채널로 전달한다.
|
|
- 생성되는 `node.yaml`의 `transport.edge_addr`만 외부 접속 주소인 `toki-labs.com:19090`으로 맞춘다.
|
|
|
|
## 현재 테스트 값
|
|
|
|
- live version: `field-live-20260527-19ddd9bd38b7`
|
|
- node token: `iop-field-20260527-7fd4c675`
|
|
- node id: `node-silicon-ollama`
|
|
- model: `gemma4:26b`
|
|
- edge config 후보: `/tmp/iop-edge-field-bootstrap.yaml`
|
|
|
|
위 값은 임시 field 테스트 값이다. 장기 규약으로 고정하지 않는다.
|
|
|
|
## 재개 전 확인
|
|
|
|
stale process가 남아 있는지 먼저 본다.
|
|
|
|
```bash
|
|
ps -ef | rg 'python3 -m http.server 18080|go run ./apps/edge/cmd/edge|/tmp/go-build.*/edge serve|iop-edge serve'
|
|
netstat -ltnp 2>/dev/null | rg ':(18080|8080|9090)\b|Proto' || true
|
|
```
|
|
|
|
이전 테스트 프로세스가 남아 있으면 정리한 뒤 새 설정으로 띄운다.
|
|
|
|
## 권장 테스트 흐름
|
|
|
|
Apple Silicon bootstrap artifact를 만들 때 artifact URL과 edge runtime 주소를 분리한다.
|
|
|
|
```bash
|
|
VERSION=field-live-20260527-19ddd9bd38b7 \
|
|
APPS=node \
|
|
TARGETS="darwin/arm64" \
|
|
ARTIFACT_BASE_URL="<internal-artifact-url>" \
|
|
BOOTSTRAP_EDGE_ADDR="toki-labs.com:19090" \
|
|
DIST_DIR=dist/field \
|
|
./bin/build/field-binaries.sh
|
|
```
|
|
|
|
artifact HTTP가 필요하면 내부에서 접근 가능한 경로로만 연다.
|
|
|
|
```bash
|
|
python3 -m http.server 18080 --bind 127.0.0.1 -d dist/field/field-live-20260527-19ddd9bd38b7
|
|
```
|
|
|
|
Edge는 field config로 실행한다.
|
|
|
|
```bash
|
|
go run ./apps/edge/cmd/edge serve --config /tmp/iop-edge-field-bootstrap.yaml
|
|
```
|
|
|
|
기본 확인:
|
|
|
|
```bash
|
|
curl -fsS http://127.0.0.1:8080/healthz
|
|
curl -fsS http://127.0.0.1:8080/v1/models
|
|
nc -vz toki-labs.com 19090
|
|
```
|
|
|
|
사용자에게 전달하는 bootstrap 명령의 URL은 artifact 전달 채널에 맞춰 작업자가 완성한다.
|
|
사용자 명령은 token 값 하나만 인자로 받는다. 사용자에게 `<artifact-base-url>` 같은 placeholder를 채우게 하지 않는다.
|
|
외부 18080을 열지 않는 흐름에서는 bootstrap script 안의 기본 Edge runtime 주소만 `19090`으로 들어가야 한다.
|
|
|
|
```bash
|
|
curl -fsSL <완성된-bootstrap-url> | bash -s iop-field-20260527-7fd4c675
|
|
```
|
|
|
|
## 성공 기준
|
|
|
|
- Node host에서 `toki-labs.com:19090`에 연결할 수 있다.
|
|
- Edge 로그에 `node registered`가 나온다.
|
|
- `/v1/models`가 `gemma4:26b`를 반환한다.
|
|
- OpenAI-compatible 호출에서 비어 있지 않은 응답 또는 SSE delta가 나온다.
|
|
|
|
## 주의
|
|
|
|
- `curl http://toki-labs.com:18080/... | bash`는 외부 18080 공개를 전제로 하므로 기본 안내로 쓰지 않는다.
|
|
- Cline 전용 감지나 provider별 분기는 만들지 않는다. OpenAI-compatible protocol 차원에서 안정화한다.
|
|
- 기본 `configs/*.yaml`에 field token이나 임시 host 값을 넣지 않는다.
|
|
- 테스트 후에는 임시 edge와 artifact server를 내려둔다.
|