@yuuki824/kanshi 0.1.0

package/.env.example

@@ -0,0 +1,19 @@
+# Copy to .env to override. Every value here is the built-in default.
+
+# Bind address. The Tailscale IP of this host keeps the dashboard off the LAN
+# and off the public interface; 0.0.0.0 exposes it everywhere.
+KANSHI_HOST=100.73.243.14
+KANSHI_PORT=8100
+
+# Live metrics
+KANSHI_POLL_INTERVAL=5
+KANSHI_DOCKER_CONCURRENCY=8
+KANSHI_IDLE_TIMEOUT=30
+
+# Storage treemap
+KANSHI_STORAGE_ROOTS=/mnt/data=/mnt/data,/=/hostfs
+KANSHI_STORAGE_INTERVAL=1800
+# Paths to skip entirely, comma separated (container-side paths).
+# The biggest win is /hostfs/var/lib/docker — ~100k overlay2 files.
+KANSHI_STORAGE_EXCLUDE=
+KANSHI_TREE_DEPTH=4

package/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+WORKDIR /opt/kanshi
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app ./app
+COPY web ./web
+
+EXPOSE 8100
+
+# Probe the address uvicorn actually bound to — with network_mode: host that
+# may be the Tailscale IP rather than loopback.
+HEALTHCHECK --interval=60s --timeout=5s --start-period=15s --retries=3 \
+  CMD python -c "import os,urllib.request,sys; \
+h=os.environ.get('KANSHI_HOST','127.0.0.1'); h='127.0.0.1' if h=='0.0.0.0' else h; \
+sys.exit(0 if urllib.request.urlopen('http://%s:%s/healthz' % (h, os.environ.get('KANSHI_PORT','8100')), timeout=4).status==200 else 1)"
+
+CMD ["sh", "-c", "exec python -m uvicorn app.main:app \
+  --host ${KANSHI_HOST:-0.0.0.0} --port ${KANSHI_PORT:-8100} \
+  --no-access-log --timeout-keep-alive 65"]

package/README.md

@@ -0,0 +1,138 @@
+# kanshi
+
+A one-page, mobile-first glance at this homeserver: live CPU and RAM, a
+Filelight-style storage treemap, and `docker stats` for every container — no
+historical storage, no alerting, no external services.
+
+Reachable from any device on the tailnet:
+
+    http://homeserver.tail7ec1d9.ts.net:8100
+
+## Install with npx
+
+`npx` downloads and runs an npm package; it does not upload a project. This
+repository includes a small npm launcher which starts the included Docker
+Compose app, so Docker (with the Compose v2 plugin) is still required.
+
+From a directory containing your `.env` file:
+
+```sh
+npx @yuuki824/kanshi
+```
+
+The command is equivalent to `docker compose up -d --build`. It reads a `.env`
+file from the directory where you run it, so first copy the template and set a
+safe `KANSHI_HOST` for the host being monitored:
+
+```sh
+cp .env.example .env
+# edit .env, then:
+npx @yuuki824/kanshi
+```
+
+Pass Docker Compose commands after the package name, for example:
+
+```sh
+npx @yuuki824/kanshi logs -f
+npx @yuuki824/kanshi down
+```
+
+To publish the launcher, use:
+
+```sh
+npm login
+npm run test
+npm run pack:check
+npm publish
+```
+
+The scoped package is configured to publish publicly. Use a unique package
+name you control; `npm publish --dry-run` is a final check that uploads nothing.
+
+## Run it
+
+```sh
+docker compose up -d --build
+```
+
+Copy `.env.example` to `.env` to override anything. Every setting has a
+conservative default; the file documents each one.
+
+## What it shows
+
+| Card | Source | Refresh |
+|---|---|---|
+| Processor — hero %, per-core bars, load, temp, host net/disk throughput | `psutil` over `/proc` | every `KANSHI_POLL_INTERVAL` (5s) |
+| Memory & volumes — RAM, swap, one meter per storage root | `psutil` + `statvfs` | same tick |
+| Storage map — squarified treemap, tap to drill, table twin below | cached `os.scandir` walk | every `KANSHI_STORAGE_INTERVAL` (30m), or the Rescan button |
+| Containers — CPU%, memory, network rates, health | Docker Engine API | same tick |
+
+The browser holds **one SSE connection** (`/api/stream`) and the server pushes
+each tick, so nothing polls and nothing needs a manual reload. There is also a
+plain REST surface: `/api/vitals`, `/api/containers`, `/api/storage`,
+`POST /api/storage/rescan`, `/healthz`.
+
+## Design notes
+
+**It stops working when you stop looking.** After `KANSHI_IDLE_TIMEOUT` with no
+browser attached, the poller stops entirely and the Docker socket goes
+untouched until someone loads the page. Idle cost is ~0.2% of one core.
+
+**One-shot container stats.** `GET /containers/{id}/stats?stream=false` makes the
+daemon block for a full collection cycle so it can populate `precpu_stats` —
+measured at **8.3s per tick** across 31 containers. Kanshi uses `one-shot=true`
+(**0.07s**) and computes CPU% against the previous tick itself. Same arithmetic,
+and a 5s window is steadier to read than the daemon's 1s one.
+
+**The disk walk is depth-bounded.** The tree is pruned to `KANSHI_TREE_DEPTH`
+before it is served, so the walk only materialises a node for directories within
+that depth — ~2.3k instead of ~96k on this host. Deeper directories are still
+fully traversed and counted; their bytes roll up into the nearest kept ancestor.
+Sizes come from `st_blocks` (so they match `du`, not apparent size) and
+hardlinked files are counted once.
+
+**The walk runs at `nice 10`** in a worker thread. A full pass over `/` takes
+~47s, and the live cards keep their exact 5s cadence throughout.
+
+**Unreadable directories are reported, not hidden.** If the walk cannot enter a
+directory it is counted and the storage card says so — a silently truncated tree
+that under-reports by 300 GB is worse than an obviously incomplete one.
+
+## Access
+
+The port is bound to the **Tailscale interface only** (`KANSHI_HOST`), so the
+dashboard is not exposed on the LAN or the public interface and needs no auth
+layer of its own. Set `KANSHI_HOST=0.0.0.0` to expose it on the LAN — but note
+that anything that can reach this app can reach the Docker socket through it, so
+add an auth proxy first if you do.
+
+If Tailscale is down when Docker starts, the bind fails and `restart:
+unless-stopped` retries until `tailscale0` is back.
+
+## Permissions
+
+Runs as root with `cap_drop: ALL` plus **`DAC_READ_SEARCH`** — read and traverse
+bypass, but *not* write bypass (that would be `DAC_OVERRIDE`). Without it the
+walk cannot enter `/home/yuuki` (mode 0750) and silently under-reports the root
+filesystem by ~330 GB. The rootfs is read-only and every host mount is `:ro`.
+
+## About kanshi's own memory number
+
+The dashboard will show kanshi using far more memory than you'd expect for a
+10 MB Python process. That figure is mostly **reclaimable kernel dentry cache**
+charged to its cgroup — an unavoidable side effect of `stat`-ing ~150k files
+during a walk. Actual anonymous memory is ~27 MB; `mem_limit` acts as a ceiling
+on the cache and the kernel reclaims it under pressure. The number matches what
+`docker stats` reports for any container, which is the point.
+
+## Tuning
+
+Slowest thing here is the walk of `/`, dominated by ~100k overlay2 files under
+`/var/lib/docker`. To skip it:
+
+```sh
+KANSHI_STORAGE_EXCLUDE=/hostfs/var/lib/docker
+```
+
+Its ~48 GB then disappears from the `/` total, so only do this if you don't want
+it counted.

package/app/config.py

@@ -0,0 +1,72 @@
+"""Runtime configuration, all via environment variables.
+
+Defaults are deliberately conservative: this box has 4 cores and ~28 other
+containers, so Kanshi should be invisible in `docker stats`.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, "") or default)
+    except ValueError:
+        return default
+
+
+def _float(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name, "") or default)
+    except ValueError:
+        return default
+
+
+def _list(name: str, default: str) -> list[str]:
+    raw = os.environ.get(name, "") or default
+    return [p.strip() for p in raw.split(",") if p.strip()]
+
+
+@dataclass(frozen=True)
+class Config:
+    # How often the live poller samples vitals + container stats, in seconds.
+    poll_interval: float = field(default_factory=lambda: _float("KANSHI_POLL_INTERVAL", 5.0))
+
+    # Stop polling entirely once no browser has been connected for this long.
+    # Nobody is looking, so there is no reason to keep waking the Docker daemon.
+    idle_timeout: float = field(default_factory=lambda: _float("KANSHI_IDLE_TIMEOUT", 30.0))
+
+    # Max concurrent /stats requests against the Docker socket per tick.
+    docker_concurrency: int = field(default_factory=lambda: _int("KANSHI_DOCKER_CONCURRENCY", 8))
+    docker_socket: str = field(default_factory=lambda: os.environ.get("KANSHI_DOCKER_SOCKET", "/var/run/docker.sock"))
+
+    # Storage walk. Roots are "label=path" or just "path".
+    storage_roots: list[str] = field(default_factory=lambda: _list("KANSHI_STORAGE_ROOTS", "/mnt/data=/mnt/data,/=/hostfs"))
+    storage_interval: float = field(default_factory=lambda: _float("KANSHI_STORAGE_INTERVAL", 1800.0))
+    # Absolute container-side paths to skip entirely. Their bytes vanish from
+    # the totals, so only exclude things you truly don't want counted.
+    storage_exclude: list[str] = field(default_factory=lambda: _list("KANSHI_STORAGE_EXCLUDE", ""))
+    storage_min_rescan: float = field(default_factory=lambda: _float("KANSHI_STORAGE_MIN_RESCAN", 30.0))
+
+    # Tree pruning, to keep the JSON the phone downloads small.
+    tree_depth: int = field(default_factory=lambda: _int("KANSHI_TREE_DEPTH", 4))
+    # Children smaller than this fraction of their parent are folded into an
+    # aggregate node rather than shipped individually.
+    tree_min_fraction: float = field(default_factory=lambda: _float("KANSHI_TREE_MIN_FRACTION", 0.005))
+    tree_max_children: int = field(default_factory=lambda: _int("KANSHI_TREE_MAX_CHILDREN", 24))
+
+    host: str = field(default_factory=lambda: os.environ.get("KANSHI_HOST", "0.0.0.0"))
+    port: int = field(default_factory=lambda: _int("KANSHI_PORT", 8100))
+
+    def roots(self) -> list[tuple[str, str]]:
+        out: list[tuple[str, str]] = []
+        for entry in self.storage_roots:
+            label, _, path = entry.partition("=")
+            if not path:
+                label, path = os.path.basename(label.rstrip("/")) or label, label
+            out.append((label, path))
+        return out
+
+
+config = Config()

package/app/dockerstats.py

@@ -0,0 +1,207 @@
+"""Docker Engine API client over the unix socket.
+
+Uses `GET /containers/{id}/stats?stream=false&one-shot=true`. The one-shot form
+returns immediately; without it the daemon blocks each request for a full
+collection cycle to produce `precpu_stats`, which measured 8.3s per tick across
+31 containers versus 0.07s here.
+
+The tradeoff is that one-shot zeroes `precpu_stats`, so CPU% is computed against
+the previous tick's counters instead — the same thing the daemon would have
+done, just over the poll interval rather than a 1s window. That is also a
+steadier number to read at a glance.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+
+import httpx
+
+from .config import config
+
+API_VERSION = "v1.43"
+
+_prev_net: dict[str, tuple[float, int, int]] = {}
+_prev_cpu: dict[str, tuple[int, int]] = {}   # cid -> (total_usage, system_usage)
+_client: httpx.AsyncClient | None = None
+
+
+def client() -> httpx.AsyncClient:
+    global _client
+    if _client is None:
+        _client = httpx.AsyncClient(
+            transport=httpx.AsyncHTTPTransport(uds=config.docker_socket, retries=1),
+            base_url=f"http://docker/{API_VERSION}",
+            timeout=httpx.Timeout(20.0, connect=5.0),
+        )
+    return _client
+
+
+async def close() -> None:
+    global _client
+    if _client is not None:
+        await _client.aclose()
+        _client = None
+
+
+def _cpu_percent(cid: str, stats: dict) -> float:
+    """CPU% against the previous tick. 100% = one full core, as `docker stats`."""
+    cpu = stats.get("cpu_stats") or {}
+    usage = (cpu.get("cpu_usage") or {}).get("total_usage")
+    system = cpu.get("system_cpu_usage")
+    if usage is None or system is None:
+        return 0.0
+
+    prev = _prev_cpu.get(cid)
+    _prev_cpu[cid] = (usage, system)
+    if prev is None:
+        return 0.0  # first sighting; the next tick has a real delta
+
+    cpu_delta = usage - prev[0]
+    sys_delta = system - prev[1]
+    # A restarted container resets its counters — report 0 rather than a
+    # nonsensical negative or a huge spike.
+    if sys_delta <= 0 or cpu_delta < 0:
+        return 0.0
+    # online_cpus is absent on older daemons; fall back to the per-cpu array.
+    ncpu = cpu.get("online_cpus") or len((cpu.get("cpu_usage") or {}).get("percpu_usage") or []) or 1
+    return round(min(cpu_delta / sys_delta * ncpu * 100.0, ncpu * 100.0), 2)
+
+
+def _memory(stats: dict) -> tuple[int, int]:
+    mem = stats.get("memory_stats") or {}
+    usage = mem.get("usage")
+    if usage is None:
+        return (0, 0)
+    detail = mem.get("stats") or {}
+    # Match `docker stats`: subtract page cache so the number reflects the
+    # working set. cgroup v2 exposes inactive_file, v1 exposes cache.
+    if "inactive_file" in detail:
+        usage -= min(detail["inactive_file"], usage)
+    elif "cache" in detail:
+        usage -= min(detail["cache"], usage)
+    return (usage, mem.get("limit") or 0)
+
+
+def _network(cid: str, stats: dict, now: float) -> dict | None:
+    networks = stats.get("networks")
+    if not networks:
+        # Containers on `network_mode: service:...` (e.g. behind gluetun) report
+        # no interfaces of their own — their traffic shows up on the provider.
+        _prev_net.pop(cid, None)
+        return None
+    rx = sum(n.get("rx_bytes", 0) for n in networks.values())
+    tx = sum(n.get("tx_bytes", 0) for n in networks.values())
+    prev = _prev_net.get(cid)
+    _prev_net[cid] = (now, rx, tx)
+    rate_rx = rate_tx = 0.0
+    if prev and now > prev[0]:
+        dt = now - prev[0]
+        # A restarted container resets its counters; clamp instead of going negative.
+        rate_rx = max(0, rx - prev[1]) / dt
+        rate_tx = max(0, tx - prev[2]) / dt
+    return {"rx": rx, "tx": tx, "rx_rate": rate_rx, "tx_rate": rate_tx}
+
+
+def _block_io(stats: dict) -> dict | None:
+    entries = (stats.get("blkio_stats") or {}).get("io_service_bytes_recursive")
+    if not entries:
+        return None  # commonly empty under cgroup v2
+    read = sum(e.get("value", 0) for e in entries if e.get("op", "").lower() == "read")
+    write = sum(e.get("value", 0) for e in entries if e.get("op", "").lower() == "write")
+    return {"read": read, "write": write}
+
+
+def _identify(meta: dict) -> tuple[str, str, str]:
+    """(full name, display name, project).
+
+    Runtipi names containers `<project>-<service>-1`, so at phone width three
+    Immich containers all truncate to the same "immich_migra…". The compose
+    labels carry the service name on its own, which is what actually
+    distinguishes them.
+    """
+    full = (meta.get("Names") or ["/?"])[0].lstrip("/")
+    labels = meta.get("Labels") or {}
+    service = labels.get("com.docker.compose.service") or ""
+    project = labels.get("com.docker.compose.project") or ""
+    return full, (service or full), project
+
+
+async def _one(cid: str, meta: dict, sem: asyncio.Semaphore) -> dict | None:
+    async with sem:
+        try:
+            r = await client().get(f"/containers/{cid}/stats", params={"stream": "false", "one-shot": "true"})
+            r.raise_for_status()
+            stats = r.json()
+        except Exception:
+            return None
+    now = time.monotonic()
+    used, limit = _memory(stats)
+    full, name, project = _identify(meta)
+    state = meta.get("State", "")
+    health = ((meta.get("Status") or "").split("(")[-1].rstrip(")") if "(" in (meta.get("Status") or "") else None)
+    return {
+        "id": cid[:12],
+        "name": name,
+        "full_name": full,
+        "project": project,
+        "image": meta.get("Image", ""),
+        "state": state,
+        "status": meta.get("Status", ""),
+        "health": health if health in ("healthy", "unhealthy", "health: starting", "starting") else None,
+        "created": meta.get("Created", 0),
+        "cpu": _cpu_percent(cid, stats),
+        "mem_used": used,
+        "mem_limit": limit,
+        "mem_percent": round(used / limit * 100, 2) if limit else 0.0,
+        "pids": (stats.get("pids_stats") or {}).get("current", 0),
+        "net": _network(cid, stats, now),
+        "blkio": _block_io(stats),
+    }
+
+
+async def sample() -> dict:
+    """One full pass: list containers, then fetch stats for the running ones."""
+    try:
+        r = await client().get("/containers/json", params={"all": "true"})
+        r.raise_for_status()
+        listing = r.json()
+    except Exception as exc:
+        return {"error": f"{type(exc).__name__}: {exc}", "containers": []}
+
+    running = [c for c in listing if c.get("State") == "running"]
+    sem = asyncio.Semaphore(max(1, config.docker_concurrency))
+    results = await asyncio.gather(*(_one(c["Id"], c, sem) for c in running))
+    containers = [c for c in results if c]
+
+    # Keep stopped containers visible but without stats, so a crashed service
+    # is obvious at a glance rather than silently missing from the list.
+    for c in listing:
+        if c.get("State") != "running":
+            full, name, project = _identify(c)
+            containers.append({
+                "id": c["Id"][:12],
+                "name": name,
+                "full_name": full,
+                "project": project,
+                "image": c.get("Image", ""),
+                "state": c.get("State", ""),
+                "status": c.get("Status", ""),
+                "health": None,
+                "created": c.get("Created", 0),
+                "cpu": 0.0, "mem_used": 0, "mem_limit": 0, "mem_percent": 0.0,
+                "pids": 0, "net": None, "blkio": None,
+            })
+
+    live = {c["Id"] for c in running}
+    for stale in [k for k in _prev_net if k not in live]:
+        _prev_net.pop(stale, None)
+    for stale in [k for k in _prev_cpu if k not in live]:
+        _prev_cpu.pop(stale, None)
+
+    containers.sort(key=lambda c: (c["state"] != "running", -c["cpu"], c["name"]))
+    return {
+        "containers": containers,
+        "running": len(running),
+        "total": len(listing),
+    }

package/app/main.py

@@ -0,0 +1,174 @@
+"""Kanshi — at-a-glance vitals for a single homeserver."""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import time
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from . import dockerstats, storage, vitals
+from .config import config
+
+WEB = Path(__file__).resolve().parent.parent / "web"
+
+_subscribers: set[asyncio.Queue] = set()
+_latest: dict = {"vitals": None, "docker": None}
+_wake = asyncio.Event()
+_last_seen = 0.0
+
+
+async def _sample_once() -> dict:
+    host, containers = await asyncio.gather(
+        asyncio.to_thread(vitals.sample),
+        dockerstats.sample(),
+    )
+    _latest["vitals"], _latest["docker"] = host, containers
+    return {"vitals": host, "docker": containers}
+
+
+async def _seed() -> None:
+    """Fill the delta baselines so the first frame shows real numbers.
+
+    Both CPU readings are differences against a previous sample, so a cold
+    poller would otherwise publish a screen of zeros. One throwaway pass plus a
+    short gap costs ~0.1s and makes the first frame the user sees correct.
+    """
+    vitals.prime()
+    try:
+        await dockerstats.sample()
+    except Exception:
+        pass
+    await asyncio.sleep(1.0)
+    vitals.prime()
+
+
+async def _poller() -> None:
+    await _seed()
+    while True:
+        idle = not _subscribers and (time.monotonic() - _last_seen) > config.idle_timeout
+        if idle:
+            # Nobody is watching: stop touching the Docker socket entirely and
+            # wait to be woken by a new subscriber or a REST request.
+            _wake.clear()
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(_wake.wait(), timeout=60.0)
+            await _seed()
+            continue
+
+        try:
+            payload = await _sample_once()
+        except Exception as exc:
+            payload = {"error": f"{type(exc).__name__}: {exc}"}
+        for queue in list(_subscribers):
+            if queue.full():
+                with contextlib.suppress(asyncio.QueueEmpty):
+                    queue.get_nowait()  # drop the stale frame, never block the poller
+            with contextlib.suppress(asyncio.QueueFull):
+                queue.put_nowait(payload)
+        await asyncio.sleep(config.poll_interval)
+
+
+def _touch() -> None:
+    global _last_seen
+    _last_seen = time.monotonic()
+    _wake.set()
+
+
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI):
+    tasks = [asyncio.create_task(_poller()), asyncio.create_task(storage.loop())]
+    try:
+        yield
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await dockerstats.close()
+
+
+app = FastAPI(title="Kanshi", lifespan=lifespan, docs_url=None, redoc_url=None)
+
+
+@app.get("/api/vitals")
+async def api_vitals():
+    _touch()
+    if _latest["vitals"] is None:
+        await _sample_once()
+    return _latest["vitals"]
+
+
+@app.get("/api/containers")
+async def api_containers():
+    _touch()
+    if _latest["docker"] is None:
+        await _sample_once()
+    return _latest["docker"]
+
+
+@app.get("/api/storage")
+async def api_storage():
+    snap = storage.snapshot()
+    if snap["scanned_at"] is None and not snap["scanning"]:
+        await storage.scan(force=True)
+        snap = storage.snapshot()
+    return snap
+
+
+@app.post("/api/storage/rescan")
+async def api_rescan():
+    return await storage.scan()
+
+
+@app.get("/api/config")
+async def api_config():
+    return {
+        "poll_interval": config.poll_interval,
+        "storage_interval": config.storage_interval,
+        "tree_depth": config.tree_depth,
+    }
+
+
+@app.get("/healthz")
+async def healthz():
+    return {"ok": True}
+
+
+@app.get("/api/stream")
+async def api_stream():
+    queue: asyncio.Queue = asyncio.Queue(maxsize=1)
+    _subscribers.add(queue)
+    _touch()
+
+    async def events():
+        try:
+            if _latest["vitals"] is not None:
+                yield f"data: {json.dumps(_latest)}\n\n"
+            while True:
+                try:
+                    payload = await asyncio.wait_for(queue.get(), timeout=25.0)
+                except asyncio.TimeoutError:
+                    yield ": keepalive\n\n"  # keeps mobile proxies from closing the stream
+                    continue
+                _touch()
+                yield f"data: {json.dumps(payload)}\n\n"
+        finally:
+            _subscribers.discard(queue)
+
+    return StreamingResponse(
+        events(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache, no-transform", "X-Accel-Buffering": "no", "Connection": "keep-alive"},
+    )
+
+
+@app.get("/")
+async def index():
+    return FileResponse(WEB / "index.html", headers={"Cache-Control": "no-cache"})
+
+
+app.mount("/static", StaticFiles(directory=WEB), name="static")