iop/docs/edge-local-dev-guide.md

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/에 맞춰 둔다.

make build

Edge 또는 Node만 갱신할 때도 같은 빌드 통로를 사용한다.

make build-edge
make build-node

산출물:

bin/iop-edge
bin/iop-node

2. Bundle 디렉터리 준비

하나의 디렉터리에 iop-edge와 iop-node 바이너리가 함께 있다고 가정한다.

/opt/iop-dev/
  iop-edge
  iop-node

repo-local 테스트는 bin/을 그대로 bundle 디렉터리로 사용할 수 있다.

cd bin

별도 디렉터리에서 테스트할 때는 repo root에서 빌드된 바이너리만 옮긴 뒤 그 디렉터리에서 실행한다.

mkdir -p /opt/iop-dev
cp bin/iop-edge bin/iop-node /opt/iop-dev/
cd /opt/iop-dev

3. Edge config 생성

./iop-edge config init

기대 결과:

<bundle-dir>/edge.yaml

edge.yaml은 Control Plane이 없는 동안 테스트용 source of truth다. 처음부터 직접 작성하지 않고 iop-edge가 생성한 템플릿에서 시작한다.

4. 현재 환경 확인

./iop-edge env

출력에서 최소한 아래 항목을 확인한다.

config path
binary dir
log dir
artifact dir
advertise host
Node transport address
artifact/bootstrap URL
OpenAI-compatible URL
configured nodes
connected nodes

advertise host가 비어 있으면 iop-edge가 host 기준으로 자동 판별한다. 명시 설정이 있으면 자동 판별보다 설정값을 따른다.

로그 기본 위치는 바이너리 디렉터리 아래다.

<bundle-dir>/logs/

5. Bootstrap artifact 준비

Node host에서 bootstrap 명령까지 테스트하려면 iop-edge serve가 제공할 artifact 폴더를 준비한다.

./iop-edge bootstrap pack

기본 산출물:

<bundle-dir>/artifacts/
  bootstrap/node-<os>-<arch>.sh
  <os>-<arch>/iop-node
  <os>-<arch>/SHA256SUMS

Mac Node host용 artifact가 필요하면 repo root에서 대상 platform을 지정해 pack한다.

make pack-node-target NODE_TARGET=darwin-arm64

Intel Mac이면 NODE_TARGET=darwin-amd64를 사용한다.

6. Node 등록과 bootstrap 출력

Node 정의는 edge.yaml을 직접 편집하지 않고 iop-edge node register로 만든다.

기본 등록:

./iop-edge node register node-silicon-ollama

Ollama Node로 등록할 때:

./iop-edge node register node-silicon-ollama \
  --target darwin-arm64 \
  --adapter ollama \
  --ollama-base-url http://127.0.0.1:11434

이 명령은 edge.yaml의 nodes[]를 생성 또는 갱신하고, 마지막에 Node host에서 실행할 bootstrap 명령을 출력한다.

출력 예:

curl -fsSL <bootstrap-url> | bash -s <generated-token>

사용자는 이 한 줄만 Node host에서 실행한다. 전달받은 명령에 IOP_ARTIFACT_BASE_URL=, IOP_EDGE_ADDR=, IOP_NODE_TOKEN= 같은 named parameter가 있으면 기본 경로가 아니다.

7. Config 검증

./iop-edge config check

이 단계에서 nodes[] token/id/alias 충돌, adapter/runtime 설정 오류가 잡혀야 한다.

8. Edge 실행

개발 중 foreground 실행:

./iop-edge serve

serve는 Edge transport와 함께 bootstrap artifact 서버도 시작한다. 기본 artifact 경로는 <bundle-dir>/artifacts/이고 기본 bootstrap URL 포트는 18080이다.

서비스로 올릴 때:

sudo ./iop-edge setup --enable --start

로그 확인:

tail -f logs/edge.log

9. Node host에서 bootstrap 실행

iop-edge node register ...가 출력한 한 줄을 Node host에서 그대로 실행한다.

curl -fsSL <bootstrap-url> | bash -s <generated-token>

Node host 사용자는 node.yaml을 만들거나 편집하지 않는다. Node 프로세스 실행 방식은 bootstrap 내부 구현 세부다.

10. 연결 확인

Edge host 로그에서 Node 등록 이벤트를 확인한다.

tail -f logs/edge.log

기대 로그:

node registered

설정에 등록된 Node 목록은 아래 명령으로 확인한다.

./iop-edge nodes list

OpenAI-compatible smoke는 OpenAI 입력 표면과 Ollama model 설정이 완료된 뒤 실행한다.

./iop-edge smoke openai --model gemma4:26b

11. Cline 접속 정보 확인

./iop-edge env

출력의 OpenAI-compatible URL을 Cline에 넣는다.

Base URL: <OpenAI-compatible URL>
Model: gemma4:26b
API Key: ASCII 값

API Key에는 한글이나 non-ASCII 문자를 넣지 않는다.

12. 문제 발생 시 공유할 것

./iop-edge env
./iop-edge nodes list
./iop-edge config check
tail -n 120 logs/edge.log

공유할 때 token 값은 지운다.