diff --git a/docs/field-bootstrap-user-test.md b/docs/field-bootstrap-user-test.md index 5cbbf6a..86710ca 100644 --- a/docs/field-bootstrap-user-test.md +++ b/docs/field-bootstrap-user-test.md @@ -1,36 +1,180 @@ -# Field Bootstrap 직접 테스트 +# Edge-local Dev 테스트 세팅 -Apple Silicon Mac에서 아래만 실행한다. -작업자는 bootstrap URL이 완성된 명령을 전달해야 한다. -사용자는 마지막 token 값 하나만 전달받은 실제 테스트 token으로 바꾼다. -이 token은 Edge 설정의 `nodes[].token`과 같은 값이어야 한다. +이 문서는 Control Plane 없이 로컬 또는 개발 서버에서 Edge/Node bundle을 빠르게 세팅하고 확인하는 사용자용 흐름이다. +사용자는 `iop-edge`를 중심으로 진행한다. -## 1. Ollama 준비 +하지 않는다: -```bash -ollama pull gemma4:26b -ollama list | grep 'gemma4:26b' +- `node.yaml` 생성, 편집, 확인 +- `edge.yaml`의 `nodes[]` 수동 작성 +- `iop-node serve --config ...` 직접 실행 +- `bin/*` helper나 별도 dev deploy 바이너리를 공식 경로로 사용 + +## 1. Bundle 디렉터리 준비 + +하나의 디렉터리에 `iop-edge`와 `iop-node` 바이너리가 함께 있다고 가정한다. + +```text +/opt/iop-dev/ + iop-edge + iop-node ``` -## 2. Node 연결 +이후 명령은 해당 디렉터리에서 실행한다. ```bash -curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s +cd /opt/iop-dev ``` -예를 들어 전달받은 토큰이 `abc123`이면 마지막 `` 자리만 `abc123`으로 바꾼다. -전달받은 명령에 `IOP_ARTIFACT_BASE_URL=`, `IOP_EDGE_ADDR=`, `IOP_NODE_TOKEN=` 같은 named parameter가 있거나 token이 없으면 실행하지 말고 먼저 요청한다. - -성공하면 터미널에 `starting node against toki-labs.com:19090`가 보이고, 프로세스가 계속 실행된다. -종료는 `Ctrl-C`. - -## 3. 결과 공유 - -성공/실패와 함께 아래만 공유한다. +## 2. Edge config 생성 ```bash -ollama list | grep 'gemma4:26b' +./iop-edge config init ``` -그리고 Node 연결 명령을 실행한 터미널 출력 전체를 함께 보낸다. -공유할 때 `token` 값은 지운다. +기대 결과: + +```text +/opt/iop-dev/edge.yaml +``` + +`edge.yaml`은 Control Plane이 없는 동안 테스트용 source of truth다. +처음부터 직접 작성하지 않고 `iop-edge`가 생성한 템플릿에서 시작한다. + +## 3. 현재 환경 확인 + +```bash +./iop-edge env +``` + +출력에서 최소한 아래 항목을 확인한다. + +```text +config path +binary dir +log dir +advertise host +Node transport address +artifact/bootstrap URL +OpenAI-compatible URL +configured nodes +connected nodes +``` + +`advertise host`가 비어 있으면 `iop-edge`가 host 기준으로 자동 판별한다. +명시 설정이 있으면 자동 판별보다 설정값을 따른다. + +로그 기본 위치는 바이너리 디렉터리 아래다. + +```text +/opt/iop-dev/logs/ +``` + +## 4. Node 등록과 bootstrap 출력 + +Node 정의는 `edge.yaml`을 직접 편집하지 않고 `iop-edge node register`로 만든다. + +기본 등록: + +```bash +./iop-edge node register node-silicon-ollama +``` + +Ollama Node로 등록할 때: + +```bash +./iop-edge node register node-silicon-ollama \ + --adapter ollama \ + --ollama-base-url http://127.0.0.1:11434 +``` + +이 명령은 `edge.yaml`의 `nodes[]`를 생성 또는 갱신하고, 마지막에 Node host에서 실행할 bootstrap 명령을 출력한다. + +출력 예: + +```bash +curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s +``` + +사용자는 이 한 줄만 Node host에서 실행한다. +전달받은 명령에 `IOP_ARTIFACT_BASE_URL=`, `IOP_EDGE_ADDR=`, `IOP_NODE_TOKEN=` 같은 named parameter가 있으면 기본 경로가 아니다. + +## 5. Config 검증 + +```bash +./iop-edge config check +``` + +이 단계에서 `nodes[]` token/id/alias 충돌, adapter/runtime 설정 오류가 잡혀야 한다. + +## 6. Edge 실행 + +개발 중 foreground 실행: + +```bash +./iop-edge serve +``` + +서비스로 올릴 때: + +```bash +sudo ./iop-edge setup --enable --start +``` + +로그 확인: + +```bash +tail -f logs/edge.log +``` + +## 7. Node host에서 bootstrap 실행 + +`iop-edge node register ...`가 출력한 한 줄을 Node host에서 그대로 실행한다. + +```bash +curl -fsSL http://toki-labs.com:18080/bootstrap/node-darwin-arm64.sh | bash -s +``` + +Node host 사용자는 `node.yaml`을 만들거나 편집하지 않는다. +Node 프로세스 실행 방식은 bootstrap 내부 구현 세부다. + +## 8. 연결 확인 + +Edge host에서 확인한다. + +```bash +./iop-edge nodes list +``` + +OpenAI-compatible smoke: + +```bash +./iop-edge smoke openai --model gemma4:26b +``` + +## 9. Cline 접속 정보 확인 + +```bash +./iop-edge env +``` + +출력의 OpenAI-compatible URL을 Cline에 넣는다. + +```text +Base URL: +Model: gemma4:26b +API Key: ASCII 값 +``` + +API Key에는 한글이나 non-ASCII 문자를 넣지 않는다. + +## 10. 문제 발생 시 공유할 것 + +```bash +./iop-edge env +./iop-edge nodes list +./iop-edge config check +tail -n 120 logs/edge.log +``` + +공유할 때 token 값은 지운다.