# 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를 내려둔다.