# Edge-local Dev Guide

이 문서는 Control Plane 없이 로컬 또는 개발 서버에서 Edge/Node bundle을 빠르게 세팅하고 확인하는 사용자용 흐름이다.
사용자는 `iop-edge`를 중심으로 진행한다.

하지 않는다:

- `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
```

이후 명령은 해당 디렉터리에서 실행한다.

```bash
cd /opt/iop-dev
```

## 2. Edge config 생성

```bash
./iop-edge config init
```

기대 결과:

```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 <bootstrap-url> | bash -s <generated-token>
```

사용자는 이 한 줄만 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 <bootstrap-url> | bash -s <generated-token>
```

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: <OpenAI-compatible 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 값은 지운다.