로컬 우선 코딩 어시스턴트 스택: Ollama가 Gemma 4를 Cline과 Open WebUI에 제공

# Local-First AI Dev Stack with Ollama

I can't actually execute commands in your environment, but here's the complete set of files and commands you need. Run the verification steps first, then drop in the files below.

## Step 1 — Verify Ollama

Run this in your shell:

```bash
command -v ollama && curl -sf http://localhost:11434/api/tags >/dev/null && echo "OK" || echo "MISSING"
```

If it prints `MISSING`, install per OS and stop:

- **macOS:** `brew install ollama && brew services start ollama`
- **Linux:** `curl -fsSL https://ollama.com/install.sh | sh`
- **Windows:** `winget install Ollama.Ollama` (then launch the Ollama app)

## Step 2 — Pick a Gemma 4 tag for your VRAM

Check VRAM:

```bash
# NVIDIA
nvidia-smi --query-gpu=memory.total --format=csv,noheader
# Apple Silicon (unified memory)
sysctl hw.memsize
```

Suggested tag mapping (pin the exact tag you pull):

| VRAM / Unified RAM | Tag |
|---|---|
| ≥ 24 GB | `gemma4:27b` |
| 12–23 GB | `gemma4:12b` |
| 6–11 GB | `gemma4:4b` |
| < 6 GB | `gemma4:2b` |

Pull it:

```bash
ollama pull gemma4:12b   # replace with the tag that matches your VRAM
```

Record the exact tag in `docs/local-ai.md` (template below).

## Step 3 — Smoke scripts

### `scripts/smoke_chat.py`

```python
#!/usr/bin/env python3
"""Send one non-streaming chat message to the local Ollama daemon."""
import os
import sys

from ollama import Client

MODEL = os.environ.get("OLLAMA_MODEL", "gemma4:12b")  # keep in sync with docs/local-ai.md
HOST = os.environ.get("OLLAMA_HOST", "http://localhost:11434")

def main() -> int:
    client = Client(host=HOST)
    resp = client.chat(
        model=MODEL,
        messages=[{"role": "user", "content": "Reply with a single short sentence confirming you are running locally."}],
        stream=False,
    )
    print(resp["message"]["content"])
    return 0

if __name__ == "__main__":
    sys.exit(main())
```

### `scripts/smoke_chat.mjs`

```javascript
#!/usr/bin/env node
// Send one non-streaming chat message to the local Ollama daemon.
import ollama from "ollama";

const MODEL = process.env.OLLAMA_MODEL ?? "gemma4:12b"; // keep in sync with docs/local-ai.md
const HOST = process.env.OLLAMA_HOST ?? "http://localhost:11434";

const client = new ollama.Ollama({ host: HOST });

const resp = await client.chat({
  model: MODEL,
  messages: [
    { role: "user", content: "Reply with a single short sentence confirming you are running locally." },
  ],
  stream: false,
});

console.log(resp.message.content);
```

Install the client packages (do not touch app source):

```bash
pip install ollama
npm install --no-save ollama
```

## Step 4 — `docs/local-ai.md`

```markdown
# Local AI Dev Stack (Ollama)

This repo uses a local-first AI stack backed by [Ollama](https://ollama.com).
No application source depends on it; the docs and smoke scripts here are
opt-in tooling for developers who want a fully local model endpoint.

## Pinned model

- **Tag:** `gemma4:12b`  <!-- replace with the exact tag you pulled -->
- **Daemon:** `http://localhost:11434`

The tag above is the single source of truth. Update it here and in
`scripts/smoke_chat.py` / `scripts/smoke_chat.mjs` together.

## Pointing Cline at the local endpoint

1. Open Cline → **Settings → API Provider**.
2. Choose **Ollama**.
3. Set **Base URL** to `http://localhost:11434`.
4. Set **Model** to the pinned tag from this doc (e.g. `gemma4:12b`).
5. Save. Cline will now route completions to your local daemon.

If Cline is running inside a container or remote dev box, use
`http://host.docker.internal:11434` (Docker Desktop) or the host's LAN IP —
but see the security note below before exposing the port.

## Running Open WebUI against the same daemon

Open WebUI talks to the same Ollama daemon, so both tools share the loaded
model and VRAM budget.

```bash
docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v open-webui:/app/backend/data \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/open-webui/open-webui:main
```

Then open <http://localhost:3000>. The pinned model tag will appear in the
model picker automatically.

## Model tag pinning policy

- **Always pin an explicit tag** (`gemma4:12b`), never `gemma4:latest`.
  `latest` can silently change under you and break reproducibility.
- **One tag per repo.** If you need a different size, add a new tag to this
  doc and update the smoke scripts in the same PR.
- **Record the tag in three places:** this doc, `scripts/smoke_chat.py`,
  `scripts/smoke_chat.mjs`. The `OLLAMA_MODEL` env var overrides all three
  for ad-hoc experiments but must not be committed.
- **Re-pull deliberately.** `ollama pull <tag>` is the only way to refresh a
  pinned tag; do it as an explicit step, not as part of CI.

## Security: keep port 11434 on localhost

The Ollama daemon has **no authentication**. Anyone who can reach
`http://<host>:11434` can run inference, list models, and pull new ones.

- Bind the daemon to `127.0.0.1` only. On Linux, set
  `OLLAMA_HOST=127.0.0.1:11434` in the systemd unit; on macOS/Windows the
  default is already localhost.
- **Never** expose 11434 to `0.0.0.0`, a LAN interface, or the public
  internet. Do not add it to a reverse proxy or tunnel.
- If a container needs access, use `host.docker.internal` (Docker Desktop)
  rather than publishing the port.
- Verify with: `ss -ltnp | grep 11434` — the address must be `127.0.0.1`.
```

## Step 5 — `make smoke`

Add to your `Makefile` (create it if absent; this does not touch app source):

```make
.PHONY: smoke
smoke:
	python3 scripts/smoke_chat.py
	node scripts/smoke_chat.mjs
```

Run it:

```bash
make smoke
```

Both scripts should print a one-line confirmation from the local model. If either fails, check that the daemon is up (`curl http://localhost:11434/api/tags`) and that the pinned tag is pulled (`ollama list`).