feat(dozzle): live log viewer — the first container-logs@1 provider (0.1.0)

[pofallon]

What

A Dozzle package, and the catalog-vocabulary change it needs to exist.

container-logs@1 has been implemented in Hola since 0.11.0-rc.1 — the redacting Docker façade, the provider grant, the install consent step, the sh.hola.* labels, the tests — and nothing has ever called it. This is the app that does.

Why Dozzle

Because it has never heard of Hola. It reads DOCKER_HOST like any Docker tool, so the entire integration is one line of manifest:

"provides": ["container-logs@1"]

and the server does the rest — injects a hola-docker-proxy sidecar running its own image, holds the socket read-only there, points DOCKER_HOST at it on every service in the deployment, and answers only GET on the container list, logs, events, a redacted inspect and the probes. The compose file here is mostly comment explaining what it deliberately does not contain: the socket mount a log viewer normally needs, which the validator rejects anyway.

That makes it the sharpest possible test of a provisioned contract, where "declared" and "actually working" are hardest to pull apart — unlike backup@1, where a provider can declare the contract and never wire its hooks (#159).

The catalog had to catch up first

schemas/manifest.schema.json and bin/validate-manifest.mjs knew only auth@1, backup@1 and push@1. The contract was undeclarable here even though the server has implemented it for three releases — provides: ["container-logs@1"] failed CI with "not a known capability contract". Both now carry it.

While adding it, accepts moved onto its own acceptableContractRef enum: container-logs@1 has implicit participation, so there is no acceptor side to opt into, and naming it in accepts is now a CI error rather than something Hola drops with a warning at runtime.

The packager README gained the two axes it never documented — declared vs implicit, brokered vs provisioned — plus a table of all four contracts. That table was checked against CONTRACTS in packages/shared/src/contracts.ts rather than written from memory.

What Dozzle can't do here, by design

Feature	Needs	Status
Container actions (start/stop/restart)	POST /containers/{id}/…	disabled — DOZZLE_ENABLE_ACTIONS=false
Shell into a container	POST /exec	disabled — DOZZLE_ENABLE_SHELL=false
Per-container CPU/memory stats	GET /containers/{id}/stats	outside the grant — UI degrades
Host info	GET /info	outside the grant — UI degrades

Both writes are switched off explicitly rather than left to 403 in the UI. The last two are the first real finding about where that allowlist sits, and worth a decision once this has run on a VM: stats are benign resource metrics, while /info leaks host kernel/OS/registry detail and probably should stay blocked or be redacted like inspect is.

Identity

auth.mode: forward-auth, so Authentik gates the door — and Dozzle's own forward-proxy provider is pointed at Authentik's identity headers (X-authentik-username / -email / -name; Dozzle's defaults are Authelia's), so the person who signed in is the person Dozzle shows rather than everyone sharing one anonymous session.

The README is blunt about the blast radius: anyone who can open this app can read every app's logs, and logs contain more than their authors intend. That is what the install-time consent is for.

Verification so far

• node bin/validate-manifest.mjs — all 18 manifests OK, including dozzle.
• Hola's own validateComposeDocument against the compose — no errors, no warnings.
• Every DOZZLE_* variable used was checked to exist upstream rather than assumed.
• Image pinned by digest: ghcr.io/amir20/dozzle:v11.1.0@sha256:7c4fb7f8… (linux/amd64, arm, arm64).

Not yet done: a real install. Next step is a disposable VM — install with --grant container-logs@1, confirm the sidecar appears and DOCKER_HOST is rewritten, confirm logs from other apps stream, and record exactly which calls the allowlist refuses. I'd rather land that evidence before this merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vck5KSX2CLxhohx14nb5Sh

[pofallon]

VM test results

Installed on a disposable VM (Hola 0.11.0-rc.6, Authentik mode) alongside an uptime-kuma neighbour. The package works, and it found three platform bugs — fixed in try-hola/hola#468, which this now depends on.

What the package proved

install without --grant	refused: "'dozzle' requires consent for privileged access it declares: container-logs@1", nothing deployed
install with --grant container-logs@1	completed, converged to running
hola-docker-proxy sidecar	injected by the platform, on the server's own image
DOCKER_HOST inside dozzle	tcp://hola-docker-proxy:2375
docker socket in dozzle	absent
docker socket in the proxy	present, read-only
a neighbour app's logs	readable through the grant, real log lines
sh.hola.app / sh.hola.deployment labels	present for grouping
neighbour's inspect	no Env
front door	302 to Authentik

Consent turning out to be mandatory rather than optional is a better guarantee than I described in the PR body: there is no unprivileged half-installed provider state to fall into.

The three bugs (all shape, not policy)

1. HEAD /_ping refused — Docker's client pings with HEAD first, so every standard client was rejected on its first call and reported it as "no engine".
2. GET /info refused — a client on Docker's SDK exits without it; now rebuilt from an allowlist (drops HttpProxy/HttpsProxy, RegistryConfig, Plugins, Swarm…).
3. Redacted inspect omitted HostConfig — dozzle segfaults on HostConfig.PortBindings; now present-but-empty, same nothing on the wire in a parseable shape.

After the fix: Connected to Docker, Accepting connections on :8080, healthy.

Envelope still holds

403 on: stats, archive?path=/etc/passwd, images, secrets, volumes, POST restart, POST exec, DELETE.

One thing to decide

/containers/{id}/stats stays 403, so the UI shows logs without CPU/memory graphs. Benign data and easy to add, but nothing needs it to function — I would rather widen the envelope on a real request than a nice-to-have.

Merge order

try-hola/hola#468 → a release carrying it → this. On an older server the package installs and the proxy appears, but dozzle will crash-loop.

🤖 Generated with Claude Code