feat: scaffold project with config, store, health endpoint, CI, and Dockerfile
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>
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user