91 lines
3.9 KiB
Markdown
91 lines
3.9 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 런타임 포트가 아니다.
|
|
- 현재 field 기준 bootstrap/artifact 외부 주소는 `http://toki-labs.com:18080`이다.
|
|
- bootstrap이 사용하는 Edge runtime 주소는 `toki-labs.com:19090`으로 맞춘다.
|
|
- Cline/OpenAI-compatible 외부 주소는 `http://toki-labs.com:18081/v1`이다.
|
|
- 사용자에게 보이는 bootstrap 명령은 완성된 URL과 token positional value 하나만 포함한다. `IOP_*=` named parameter를 사용자 기본 경로에 두지 않는다.
|
|
- 사용자에게 `node.yaml` 생성, 확인, 편집, `iop-node serve --config ...` 실행을 요구하지 않는다. bootstrap 내부 상태 파일은 구현 세부로만 취급한다.
|
|
|
|
## 완료 테스트 스냅샷
|
|
|
|
- live version: `field-live-20260527-19ddd9bd38b7`
|
|
- node id: `node-silicon-ollama`
|
|
- model: `gemma4:26b`
|
|
- edge config 후보: `/tmp/iop-edge-field-bootstrap.yaml`
|
|
|
|
위 값은 완료된 field 테스트의 임시 값이다. token은 테스트마다 새로 발급하고 문서값을 재사용하지 않는다.
|
|
|
|
## 재개 전 확인
|
|
|
|
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="http://toki-labs.com:18080" \
|
|
BOOTSTRAP_EDGE_ADDR="toki-labs.com:19090" \
|
|
DIST_DIR=dist/field \
|
|
./bin/build/field-binaries.sh
|
|
```
|
|
|
|
artifact HTTP가 필요하면 `18080`으로 연다.
|
|
|
|
```bash
|
|
python3 -m http.server 18080 --bind 0.0.0.0 -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를 채우게 하지 않는다.
|
|
bootstrap script 안의 기본 Edge runtime 주소는 `19090`으로 들어가야 한다.
|
|
|
|
```bash
|
|
curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s <token>
|
|
```
|
|
|
|
## 성공 기준
|
|
|
|
- Node host에서 `toki-labs.com:19090`에 연결할 수 있다.
|
|
- Edge 로그에 `node registered`가 나온다.
|
|
- `/v1/models`가 `gemma4:26b`를 반환한다.
|
|
- OpenAI-compatible 호출에서 비어 있지 않은 응답 또는 SSE delta가 나온다.
|
|
|
|
## 주의
|
|
|
|
- field 기본 경로에서는 `curl http://toki-labs.com:18080/... | bash -s <token>` 형태를 사용한다.
|
|
- `18080`을 사용할 수 없는 별도 환경에서만 내부망, front/control-plane, CI artifact, 임시 로컬 HTTP 같은 artifact 전달 채널로 바꾼다.
|
|
- Cline 전용 감지나 provider별 분기는 만들지 않는다. OpenAI-compatible protocol 차원에서 안정화한다.
|
|
- 기본 `configs/*.yaml`에 field token이나 임시 host 값을 넣지 않는다.
|
|
- 테스트 후에는 임시 edge와 artifact server를 내려둔다.
|