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:
13 files changed
+727
-4
No files matched your search
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user