feat(serve): HTTP transport + hardened Docker image for secure public serving

Add an opt-in streamable-HTTP transport alongside the default stdio, so
familiar can be reached from a home lab over HTTPS behind a TLS reverse proxy.

- config.http_settings(): env-driven transport/host/port/path/token settings.
- serve.run(): dispatch stdio vs http; fail closed on a non-loopback bind
  without a bearer token (FAMILIAR_ALLOW_INSECURE_BIND escape hatch).
- server.build_http_auth(): FastMCP StaticTokenVerifier bearer gate; add an
  unauthenticated /healthz route for container/proxy probes.
- `familiar serve` CLI alias; clean exit on InsecureBind.
- docker/Dockerfile (multi-stage, non-root) + hardened docker-compose.yml
  (read-only rootfs, cap_drop ALL, no-new-privileges, Traefik TLS labels),
  .dockerignore, .env.example. Token store mounts at /data; writes off by default.
- .gitea/workflows/docker.yml: build + smoke-test, opt-in image publish.
- docs/deployment.md + README/CLAUDE.md notes; tests for settings, fail-closed
  validation, and the bearer verifier.
This commit is contained in:
Latte committed 2026-07-03 19:55:20 +02:00
1 parent d65e9be5ff
commit f4d2dcb1d8
13 files changed
+727 -4

No files matched your search

+17
View File
@@ -77,6 +77,23 @@ To opt out and block all writes globally:
uv run familiar writes disable # turn writes off (uv run familiar writes enable to re-allow)
```
### Run it publicly (HTTP over Docker)
By default familiar talks **stdio** to a local client. It can also serve
**streamable HTTP** for reaching it from your home lab over HTTPS — opt-in,
behind a TLS reverse proxy, gated by a bearer token:
```bash
cp .env.example .env # set FAMILIAR_HTTP_AUTH_TOKEN + FAMILIAR_DOMAIN
docker compose up -d --build # Traefik/Caddy terminates TLS on the `proxy` network
```
Secure by default: it binds loopback unless told otherwise, **refuses to start**
on a public interface without a bearer token, and ships with writes off. Log in
once on a machine with a browser (`familiar login`) and mount that token store
into the container. Full walkthrough — token, TLS, client wiring — in
[docs/deployment.md](docs/deployment.md).
## Roadmap
Built in phases. Each phase is independently useful, so the project stays shippable.