# Edge-local Dev Guide 이 문서는 Control Plane 없이 로컬 또는 개발 서버에서 Edge/Node bundle을 빠르게 세팅하고 확인하는 사용자용 흐름이다. 사용자는 `iop-edge`를 중심으로 진행한다. 하지 않는다: - `node.yaml` 생성, 편집, 확인 - `edge.yaml`의 `nodes[]` 수동 작성 - `iop-node serve --config ...` 직접 실행 - `bin/*.sh` helper나 별도 dev deploy 바이너리를 공식 경로로 사용 ## 1. 빌드 공식 빌드 진입점은 `make build` 하나로 둔다. 이 명령은 Edge와 Node를 함께 빌드하고, 현재 host에서 바로 쓸 수 있는 바이너리를 `bin/`에 맞춰 둔다. ```bash make build ``` Edge 또는 Node만 갱신할 때도 같은 빌드 통로를 사용한다. ```bash make build-edge make build-node ``` 산출물: ```text bin/iop-edge bin/iop-node dist/field//-/iop-edge dist/field//-/iop-node ``` ## 2. Bundle 디렉터리 준비 하나의 디렉터리에 `iop-edge`와 `iop-node` 바이너리가 함께 있다고 가정한다. ```text /opt/iop-dev/ iop-edge iop-node ``` repo-local 테스트는 `bin/`을 그대로 bundle 디렉터리로 사용할 수 있다. ```bash cd bin ``` 별도 디렉터리에서 테스트할 때는 repo root에서 빌드된 바이너리만 옮긴 뒤 그 디렉터리에서 실행한다. ```bash mkdir -p /opt/iop-dev cp bin/iop-edge bin/iop-node /opt/iop-dev/ cd /opt/iop-dev ``` ## 3. Edge config 생성 ```bash ./iop-edge config init ``` 기대 결과: ```text /edge.yaml ``` `edge.yaml`은 Control Plane이 없는 동안 테스트용 source of truth다. 처음부터 직접 작성하지 않고 `iop-edge`가 생성한 템플릿에서 시작한다. ## 4. 현재 환경 확인 ```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 /logs/ ``` ## 5. 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 | bash -s ``` 사용자는 이 한 줄만 Node host에서 실행한다. 전달받은 명령에 `IOP_ARTIFACT_BASE_URL=`, `IOP_EDGE_ADDR=`, `IOP_NODE_TOKEN=` 같은 named parameter가 있으면 기본 경로가 아니다. ## 6. Config 검증 ```bash ./iop-edge config check ``` 이 단계에서 `nodes[]` token/id/alias 충돌, adapter/runtime 설정 오류가 잡혀야 한다. ## 7. Edge 실행 개발 중 foreground 실행: ```bash ./iop-edge serve ``` 서비스로 올릴 때: ```bash sudo ./iop-edge setup --enable --start ``` 로그 확인: ```bash tail -f logs/edge.log ``` ## 8. Node host에서 bootstrap 실행 `iop-edge node register ...`가 출력한 한 줄을 Node host에서 그대로 실행한다. ```bash curl -fsSL | bash -s ``` Node host 사용자는 `node.yaml`을 만들거나 편집하지 않는다. Node 프로세스 실행 방식은 bootstrap 내부 구현 세부다. ## 9. 연결 확인 Edge host에서 확인한다. ```bash ./iop-edge nodes list ``` OpenAI-compatible smoke: ```bash ./iop-edge smoke openai --model gemma4:26b ``` ## 10. Cline 접속 정보 확인 ```bash ./iop-edge env ``` 출력의 OpenAI-compatible URL을 Cline에 넣는다. ```text Base URL: Model: gemma4:26b API Key: ASCII 값 ``` API Key에는 한글이나 non-ASCII 문자를 넣지 않는다. ## 11. 문제 발생 시 공유할 것 ```bash ./iop-edge env ./iop-edge nodes list ./iop-edge config check tail -n 120 logs/edge.log ``` 공유할 때 token 값은 지운다.