steve
9cdf4b2472
Phase 1 of foreman: initialize the Go module, project layout, and core infrastructure. Includes env-based configuration (FOREMAN_* namespace), SQLite-backed durable job queue with WAL mode via modernc.org/sqlite, stdlib HTTP server with /healthz and optional bearer-token auth middleware, subcommand dispatch (serve + stubs), Gitea CI workflow, multi-stage distroless Dockerfile, and comprehensive tests for all packages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
64 lines
1.9 KiB
Markdown
64 lines
1.9 KiB
Markdown
# foreman
|
|
|
|
A small, always-on Go daemon that fronts **one** Ollama target. It turns a
|
|
single Ollama instance into a queued, observable job endpoint: it polls the
|
|
target's installed models, serializes work through the target (managing model
|
|
swaps), assigns every job an ID, and reports progress via webhooks.
|
|
|
|
On the wire it speaks **native Ollama**, so it doubles as a drop-in `go-llm`
|
|
target.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# Set the required Ollama target URL
|
|
export FOREMAN_OLLAMA_URL=http://mac.tail:11434
|
|
|
|
# Run directly
|
|
go run ./cmd/foreman serve
|
|
|
|
# Or build and run
|
|
go build -o foreman ./cmd/foreman
|
|
./foreman serve
|
|
```
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
docker build -t foreman .
|
|
docker run -e FOREMAN_OLLAMA_URL=http://mac.tail:11434 -p 8080:8080 foreman
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is via environment variables, namespaced under `FOREMAN_*`.
|
|
See [`.env.example`](.env.example) for the full list.
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `FOREMAN_ADDR` | `:8080` | Listen address |
|
|
| `FOREMAN_OLLAMA_URL` | *(required)* | Ollama target base URL |
|
|
| `FOREMAN_OLLAMA_TOKEN` | *(empty)* | Bearer token sent to the target |
|
|
| `FOREMAN_TOKEN` | *(empty)* | Bearer token callers must present |
|
|
| `FOREMAN_EMBED_MODEL` | *(empty)* | Always-resident embedder model |
|
|
| `FOREMAN_DB_PATH` | `foreman.db` | SQLite database path |
|
|
| `FOREMAN_POLL_INTERVAL` | `30s` | Target model poll interval |
|
|
| `FOREMAN_WEBHOOK_SECRET` | *(empty)* | HMAC key for webhook signing |
|
|
|
|
## Health check
|
|
|
|
```bash
|
|
curl http://localhost:8080/healthz
|
|
# {"status":"ok","degraded":false}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
See [`docs/adr/`](docs/adr/) for design decisions. Key points:
|
|
|
|
- One daemon per Ollama target (ADR-0001)
|
|
- SQLite-backed durable job queue in WAL mode (ADR-0008)
|
|
- Single worker loop with drain-by-model scheduling (ADR-0009)
|
|
- Native Ollama passthrough + async `/jobs` surface (ADR-0003, ADR-0004)
|
|
- Embeddings bypass the queue entirely (ADR-0013)
|