264 lines
6.2 KiB
Markdown
264 lines
6.2 KiB
Markdown
# Edge-local Dev Guide
|
|
|
|
이 문서는 Control Plane 없이 로컬 또는 개발 서버에서 Edge/Node bundle을 빠르게 세팅하고 확인하는 사용자용 흐름이다.
|
|
사용자는 `iop-edge`를 중심으로 진행한다.
|
|
|
|
하지 않는다:
|
|
|
|
- `node.yaml` 생성, 편집, 확인
|
|
- `edge.yaml`의 `nodes[]` 수동 작성
|
|
- `iop-node serve --config ...` 직접 실행
|
|
- `scripts/dev/*.sh` helper나 별도 dev deploy 바이너리를 공식 경로로 사용
|
|
|
|
## 1. 빌드와 Edge 배포 패키지
|
|
|
|
공식 빌드 진입점은 `make build` 하나로 둔다.
|
|
이 명령은 Edge와 Node를 함께 빌드하고, 현재 host에서 바로 쓸 수 있는 바이너리만 `build/bin/`에 맞춰 둔다.
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
Edge 또는 Node만 갱신할 때도 같은 빌드 통로를 사용한다.
|
|
|
|
```bash
|
|
make build-edge
|
|
make build-node
|
|
```
|
|
|
|
산출물:
|
|
|
|
```text
|
|
build/bin/iop-edge
|
|
build/bin/iop-node
|
|
```
|
|
|
|
Edge host에 배포할 때는 Node target artifact를 먼저 준비한 뒤 Edge archive를 만든다.
|
|
|
|
```bash
|
|
make pack-node-target NODE_TARGET=darwin-arm64
|
|
make pack-edge
|
|
```
|
|
|
|
Intel Mac Node면 `NODE_TARGET=darwin-amd64`를 사용한다.
|
|
Edge만 새로 빌드한 경우에는 기존 `build/artifacts/`를 유지한 상태에서 `make pack-edge`만 다시 실행한다.
|
|
Node binary를 새로 빌드한 경우에는 `make pack-node-target NODE_TARGET=<goos>-<goarch>` 후 `make pack-edge`를 다시 실행한다.
|
|
|
|
배포 산출물:
|
|
|
|
```text
|
|
build/packages/iop-edge-<edge-os>-<edge-arch>.tar.gz
|
|
```
|
|
|
|
## 2. Edge 패키지 압축 해제
|
|
|
|
Edge host에서는 archive 하나만 옮긴 뒤 압축을 푼다.
|
|
|
|
```bash
|
|
tar -xzf build/packages/iop-edge-$(go env GOOS)-$(go env GOARCH).tar.gz -C /opt
|
|
cd /opt/iop-edge-$(go env GOOS)-$(go env GOARCH)
|
|
```
|
|
|
|
압축 해제 후 기본 구조:
|
|
|
|
```text
|
|
iop-edge
|
|
artifacts/
|
|
logs/
|
|
```
|
|
|
|
repo-local에서 archive 없이 확인할 때는 새 bundle 디렉터리에 Edge binary와 artifacts를 함께 둔다.
|
|
|
|
```bash
|
|
mkdir -p /tmp/iop-edge-dev
|
|
cp build/bin/iop-edge /tmp/iop-edge-dev/
|
|
cp -R build/artifacts /tmp/iop-edge-dev/
|
|
cd /tmp/iop-edge-dev
|
|
```
|
|
|
|
## 3. Edge config 생성
|
|
|
|
```bash
|
|
./iop-edge config init
|
|
```
|
|
|
|
기대 결과:
|
|
|
|
```text
|
|
<bundle-dir>/edge.yaml
|
|
```
|
|
|
|
`edge.yaml`은 Control Plane이 없는 동안 테스트용 source of truth다.
|
|
처음부터 직접 작성하지 않고 `iop-edge`가 생성한 템플릿에서 시작한다.
|
|
|
|
## 4. 현재 환경 확인
|
|
|
|
```bash
|
|
./iop-edge env
|
|
```
|
|
|
|
출력에서 최소한 아래 항목을 확인한다.
|
|
|
|
```text
|
|
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 기준으로 자동 판별한다.
|
|
명시 설정이 있으면 자동 판별보다 설정값을 따른다.
|
|
|
|
로그 기본 위치는 바이너리 디렉터리 아래다.
|
|
|
|
```text
|
|
<bundle-dir>/logs/
|
|
```
|
|
|
|
## 5. Bootstrap artifact 확인
|
|
|
|
Edge archive에는 `make pack-node-target`으로 준비한 Node artifact가 들어 있어야 한다.
|
|
|
|
```text
|
|
artifacts/
|
|
bootstrap/node-<os>-<arch>.sh
|
|
<os>-<arch>/iop-node
|
|
<os>-<arch>/SHA256SUMS
|
|
```
|
|
|
|
`node register`는 해당 target의 `artifacts/<target>/iop-node`가 있으면 현재 `edge.yaml` 기준으로 bootstrap script와 checksum을 다시 생성한다.
|
|
즉 build machine에서 만든 archive를 다른 Edge host에 풀어도, Edge host에서 config를 확정한 뒤 등록하면 Node가 받을 URL과 Edge 주소가 현재 host 기준으로 맞춰진다.
|
|
|
|
새 Node binary를 Edge host에서 직접 교체한 경우에만 `./iop-edge bootstrap pack --target <goos>-<goarch> --node-binary <path>`로 다시 pack한다.
|
|
|
|
## 6. 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 \
|
|
--target darwin-arm64 \
|
|
--adapter ollama \
|
|
--ollama-base-url http://127.0.0.1:11434
|
|
```
|
|
|
|
이 명령은 `edge.yaml`의 `nodes[]`를 생성 또는 갱신하고, 마지막에 Node host에서 실행할 bootstrap 명령을 출력한다.
|
|
`--target` 값은 `artifacts/<target>/`에 들어 있는 Node artifact와 같아야 한다.
|
|
|
|
출력 예:
|
|
|
|
```bash
|
|
curl -fsSL <bootstrap-url> | bash -s <generated-token>
|
|
```
|
|
|
|
사용자는 이 한 줄만 Node host에서 실행한다.
|
|
전달받은 명령에 `IOP_ARTIFACT_BASE_URL=`, `IOP_EDGE_ADDR=`, `IOP_NODE_TOKEN=` 같은 named parameter가 있으면 기본 경로가 아니다.
|
|
|
|
## 7. Config 검증
|
|
|
|
```bash
|
|
./iop-edge config check
|
|
```
|
|
|
|
이 단계에서 `nodes[]` token/id/alias 충돌, adapter/runtime 설정 오류가 잡혀야 한다.
|
|
|
|
## 8. Edge 실행
|
|
|
|
개발 중 foreground 실행:
|
|
|
|
```bash
|
|
./iop-edge serve
|
|
```
|
|
|
|
`serve`는 Edge transport와 함께 bootstrap artifact 서버도 시작한다.
|
|
기본 artifact 경로는 `<bundle-dir>/artifacts/`이고 기본 bootstrap URL 포트는 `18080`이다.
|
|
|
|
서비스로 올릴 때:
|
|
|
|
```bash
|
|
sudo ./iop-edge setup --enable --start
|
|
```
|
|
|
|
로그 확인:
|
|
|
|
```bash
|
|
tail -f logs/edge.log
|
|
```
|
|
|
|
## 9. Node host에서 bootstrap 실행
|
|
|
|
`iop-edge node register ...`가 출력한 한 줄을 Node host에서 그대로 실행한다.
|
|
|
|
```bash
|
|
curl -fsSL <bootstrap-url> | bash -s <generated-token>
|
|
```
|
|
|
|
Node host 사용자는 `node.yaml`을 만들거나 편집하지 않는다.
|
|
Node 프로세스 실행 방식은 bootstrap 내부 구현 세부다.
|
|
|
|
## 10. 연결 확인
|
|
|
|
Edge host 로그에서 Node 등록 이벤트를 확인한다.
|
|
|
|
```bash
|
|
tail -f logs/edge.log
|
|
```
|
|
|
|
기대 로그:
|
|
|
|
```text
|
|
node registered
|
|
```
|
|
|
|
설정에 등록된 Node 목록은 아래 명령으로 확인한다.
|
|
|
|
```bash
|
|
./iop-edge nodes list
|
|
```
|
|
|
|
OpenAI-compatible smoke는 OpenAI 입력 표면과 Ollama model 설정이 완료된 뒤 실행한다.
|
|
|
|
```bash
|
|
./iop-edge smoke openai --model gemma4:26b
|
|
```
|
|
|
|
## 11. Cline 접속 정보 확인
|
|
|
|
```bash
|
|
./iop-edge env
|
|
```
|
|
|
|
출력의 OpenAI-compatible URL을 Cline에 넣는다.
|
|
|
|
```text
|
|
Base URL: <OpenAI-compatible URL>
|
|
Model: gemma4:26b
|
|
API Key: ASCII 값
|
|
```
|
|
|
|
API Key에는 한글이나 non-ASCII 문자를 넣지 않는다.
|
|
|
|
## 12. 문제 발생 시 공유할 것
|
|
|
|
```bash
|
|
./iop-edge env
|
|
./iop-edge nodes list
|
|
./iop-edge config check
|
|
tail -n 120 logs/edge.log
|
|
```
|
|
|
|
공유할 때 token 값은 지운다.
|