@yuuki824/kanshi 0.1.0 → 0.1.2

package/.env.example

@@ -1,8 +1,8 @@
 # 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
+# Bind address. Localhost keeps the dashboard private. Use this host's
+# Tailscale IP to share it on a tailnet; 0.0.0.0 exposes it everywhere.
+KANSHI_HOST=127.0.0.1
 KANSHI_PORT=8100
 
 # Live metrics
@@ -11,7 +11,7 @@ KANSHI_DOCKER_CONCURRENCY=8
 KANSHI_IDLE_TIMEOUT=30
 
 # Storage treemap
-KANSHI_STORAGE_ROOTS=/mnt/data=/mnt/data,/=/hostfs
+KANSHI_STORAGE_ROOTS=/=/hostfs,/mnt/data=/mnt/data
 KANSHI_STORAGE_INTERVAL=1800
 # Paths to skip entirely, comma separated (container-side paths).
 # The biggest win is /hostfs/var/lib/docker — ~100k overlay2 files.

package/Dockerfile

@@ -1,27 +1,32 @@
-FROM python:3.12-slim
+# Build stage. The module has no third-party dependencies, so there is nothing
+# to download and nothing to vendor — go.mod is copied on its own only so the
+# layer cache survives edits to the source.
+FROM golang:1.25-alpine AS build
 
-ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1 \
-    PIP_NO_CACHE_DIR=1 \
-    PIP_DISABLE_PIP_VERSION_CHECK=1
+WORKDIR /src
+COPY go.mod ./
+COPY main.go ./
+COPY internal ./internal
+COPY web ./web
 
-WORKDIR /opt/kanshi
+# CGO off because nothing here needs libc: /proc is read as plain files and the
+# Docker socket is a plain unix socket. That is what makes a scratch image
+# possible at all.
+ENV CGO_ENABLED=0
+RUN go vet ./... && \
+    go build -trimpath -ldflags="-s -w" -o /kanshi .
 
-COPY requirements.txt ./
-RUN pip install --no-cache-dir -r requirements.txt
+# Runtime stage. The web assets are embedded in the binary, so the image is one
+# static file and nothing else — no shell, no package manager, no CVE surface.
+FROM scratch
 
-COPY app ./app
-COPY web ./web
+COPY --from=build /kanshi /kanshi
 
 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)"
+# The probe is the binary itself: a scratch image has no curl to call, and this
+# way it reads KANSHI_HOST/KANSHI_PORT from the same code that binds them.
+HEALTHCHECK --interval=60s --timeout=5s --start-period=10s --retries=3 \
+  CMD ["/kanshi", "-healthcheck"]
 
-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"]
+ENTRYPOINT ["/kanshi"]

package/README.md

@@ -1,12 +1,65 @@
+<div align="center">
+
 # 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.
+**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.
+
+[![Go](https://img.shields.io/badge/Go-1.25-00add8?logo=go&logoColor=white)](https://go.dev/)
+[![Image](https://img.shields.io/badge/image-9.6MB%20scratch-0b7285)](https://hub.docker.com/_/scratch)
+[![Docker](https://img.shields.io/badge/Docker-Compose-2496ed?logo=docker&logoColor=white)](https://docs.docker.com/compose/)
+[![npm](https://img.shields.io/badge/npx-%40yuuki824%2Fkanshi-cb3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/@yuuki824/kanshi)
+
+</div>
+
+---
+
+## Screenshots
+
+<table>
+<tr>
+<td width="60%">
+
+**Vitals & storage** — live CPU/RAM meters and the storage treemap
+<img src="docs/screenshots/dashboard-vitals.png" alt="Processor, memory and storage map cards" />
+
+</td>
+<td width="40%">
+
+**Mobile** — the same cards, stacked for a phone screen
+<img src="docs/screenshots/dashboard-mobile.png" alt="Dashboard on a mobile viewport" />
+
+</td>
+</tr>
+</table>
+
+By default it is reachable only from the local machine:
 
-Reachable from any device on the tailnet:
+    http://localhost:8100
 
-    http://homeserver.tail7ec1d9.ts.net:8100
+## Features
+
+- 📊 **Processor** — hero utilisation %, per-core bars, load average, temperature, host net/disk throughput
+- 🧠 **Memory & volumes** — RAM, swap, and one meter per storage root
+- 🗺 **Storage map** — squarified treemap you can tap to drill into, with a table twin below; depth-bounded so it stays fast on large filesystems
+- 🐳 **Containers** — per-container CPU%, memory, network rate and health straight from the Docker Engine API
+- ⚡ **One SSE connection** — the server pushes every tick over `/api/stream`; nothing polls, nothing needs a manual reload
+- 😴 **Idles to near-zero** — the poller and the Docker socket both go quiet after `KANSHI_IDLE_TIMEOUT` with nobody watching
+- 🪶 **9.6 MB image, ~8 MB resident** — one static Go binary on `scratch`: no interpreter, no shell, no package manager
+- 🔒 **Tailscale-friendly** — binds to `127.0.0.1` by default; point it at a Tailscale IP to share it on a tailnet instead of the open LAN
+
+## Tech Stack
+
+| Layer | Choice |
+|---|---|
+| Backend | Go 1.25, standard library only — zero third-party dependencies |
+| Host metrics | `/proc` and `/sys` parsed directly; `statfs(2)` for volumes |
+| Live updates | Server-Sent Events (`/api/stream`) |
+| Frontend | Vanilla JS, hand-rolled SVG treemap — no build step, embedded in the binary |
+| Container metrics | Docker Engine API (one-shot stats, not the streaming daemon default) |
+| Packaging | `scratch` image via multi-stage build, Docker Compose, `npx` launcher |
 
 ## Install with npx
 
@@ -14,29 +67,70 @@ Reachable from any device on the tailnet:
 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:
+From any directory, run:
 
 ```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:
+The first run downloads the package, builds the Docker image, and starts a
+container named `kanshi`. Open <http://localhost:8100> once it says the
+container started. It may take a minute for the initial health check to pass.
+
+The command is equivalent to `docker compose up -d --build`. To run without
+the confirmation prompt:
 
 ```sh
-cp .env.example .env
-# edit .env, then:
-npx @yuuki824/kanshi
+npx --yes @yuuki824/kanshi
+```
+
+### Manage the container
+
+```sh
+# Stop it without removing it.
+docker stop kanshi
+
+# Start the stopped container again.
+docker start kanshi
+
+# Follow application logs.
+docker logs -f kanshi
+
+# Remove the current container, for example before installing an update.
+docker rm -f kanshi
+
+# Download the newest package version and start it again.
+npx @yuuki824/kanshi@latest
 ```
 
-Pass Docker Compose commands after the package name, for example:
+You can also pass Docker Compose commands after the package name:
 
 ```sh
 npx @yuuki824/kanshi logs -f
 npx @yuuki824/kanshi down
 ```
 
+### Network access
+
+Kanshi listens on `127.0.0.1:8100` by default, so it is private to the host.
+To share it over Tailscale, use the machine's Tailscale IP:
+
+```sh
+KANSHI_HOST="$(tailscale ip -4)" npx @yuuki824/kanshi
+```
+
+Do not use `KANSHI_HOST=0.0.0.0` unless the machine is protected by an
+authenticated reverse proxy: the dashboard can read Docker information.
+
+### Troubleshooting
+
+Check whether the container is running and inspect a restart or startup error:
+
+```sh
+docker ps --filter name=kanshi
+docker logs --tail=100 kanshi
+```
+
 To publish the launcher, use:
 
 ```sh
@@ -58,13 +152,13 @@ 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
+## API
 
 | 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 |
+| Processor — hero %, per-core bars, load, temp, host net/disk throughput | `/proc/stat`, `/proc/net/dev`, `/proc/diskstats`, `/sys` hwmon | every `KANSHI_POLL_INTERVAL` (5s) |
+| Memory & volumes — RAM, swap, one meter per storage root | `/proc/meminfo` + `statfs(2)` | same tick |
+| Storage map — squarified treemap, tap to drill, table twin below | cached `getdents`+`lstat` 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
@@ -91,24 +185,16 @@ 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.
+**The walk runs at `nice 10`** on a locked, dedicated OS thread — Linux applies
+`setpriority(PRIO_PROCESS)` per thread, and the runtime retires that thread when
+the walk ends rather than handing a niced thread back to the poller. A full pass
+over `/` takes ~76s on a cold cache, 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
@@ -118,12 +204,29 @@ 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.
+The dashboard will show kanshi using far more memory than the process actually
+has. That figure is mostly **reclaimable kernel dentry cache** charged to its
+cgroup — an unavoidable side effect of `lstat`-ing ~150k files during a walk.
+Measured anonymous memory is **~8 MB at rest and ~20 MB at the peak of a full
+walk**; `mem_limit` acts as a ceiling on the cache and the kernel reclaims it
+under pressure. `GOMEMLIMIT` sits below `mem_limit` so an unusually large
+filesystem makes the collector work harder instead of getting the container
+OOM-killed. The number matches what `docker stats` reports for any container,
+which is the point.
+
+## Building
+
+The only build dependency is Docker; the image compiles the binary itself.
+
+```sh
+docker compose up -d --build
+```
+
+With a local Go toolchain (1.22+), `go build .` and `go vet ./...` work from the
+repository root with no module downloads — there are no third-party imports. The
+frontend is embedded with `//go:embed`, so a rebuild is needed after editing
+anything under `web/`; set `KANSHI_WEB_DIR=./web` to serve it from disk instead
+while iterating.
 
 ## Tuning
 

package/docker-compose.yml

@@ -10,10 +10,9 @@ services:
     network_mode: host
 
     environment:
-      # Bind to the Tailscale IP only — not the LAN, not the public interface.
-      # Reachable at http://homeserver.tail7ec1d9.ts.net:8100 from any device on
-      # the tailnet. Set to 0.0.0.0 to also expose it on the LAN.
-      KANSHI_HOST: "${KANSHI_HOST:-100.73.243.14}"
+      # Localhost is safe for a package install. Set this to a Tailscale IP to
+      # share it on a tailnet, or 0.0.0.0 only behind an authenticated proxy.
+      KANSHI_HOST: "${KANSHI_HOST:-127.0.0.1}"
       KANSHI_PORT: "${KANSHI_PORT:-8100}"
 
       # Live poll cadence. Each tick is one /containers/json plus one /stats per
@@ -24,13 +23,20 @@ services:
       KANSHI_IDLE_TIMEOUT: "${KANSHI_IDLE_TIMEOUT:-30}"
 
       # Storage walk: label=path pairs. Cached, never recomputed per refresh.
-      KANSHI_STORAGE_ROOTS: "${KANSHI_STORAGE_ROOTS:-/mnt/data=/mnt/data,/=/hostfs}"
+      KANSHI_STORAGE_ROOTS: "${KANSHI_STORAGE_ROOTS:-/=/hostfs,/mnt/data=/mnt/data}"
       KANSHI_STORAGE_INTERVAL: "${KANSHI_STORAGE_INTERVAL:-1800}"
       # Container-side paths to skip. /hostfs/var/lib/docker is ~48 GB across
       # ~100k overlay2 files and dominates the walk time — uncomment to trim it.
       KANSHI_STORAGE_EXCLUDE: "${KANSHI_STORAGE_EXCLUDE:-}"
       KANSHI_TREE_DEPTH: "${KANSHI_TREE_DEPTH:-4}"
 
+      # Give the GC a budget below mem_limit so a walk on an unusually large
+      # filesystem degrades into more collection rather than an OOM kill.
+      GOMEMLIMIT: "80MiB"
+      # Two Ps is plenty for a 5s poll loop and one walk, and it keeps the Go
+      # scheduler from spreading across all four cores of a busy box.
+      GOMAXPROCS: "2"
+
     volumes:
       # Read-only on the socket is a mount flag, not an API restriction — it is
       # the Tailscale-only bind above that keeps this out of reach.
@@ -50,9 +56,12 @@ services:
       - no-new-privileges:true
 
     # Stays out of the way of the other ~28 containers on this 4-core box.
-    # Steady state is ~1% of one core; the ceiling is headroom for the walk.
+    # Steady state is ~0.03% of one core; the ceiling is headroom for the walk.
     cpus: "1.0"
-    mem_limit: 256m
+    # Measured peak during a full walk of a 2 TB host is ~20 MiB of heap, and
+    # ~8 MiB at rest. The rest of this is reclaimable page cache the walk pulls
+    # in, which the kernel drops again the moment anything else wants it.
+    mem_limit: 96m
 
     logging:
       driver: json-file

package/go.mod

@@ -0,0 +1,3 @@
+module github.com/yuuki824/kanshi
+
+go 1.22

package/internal/config/config.go

@@ -0,0 +1,140 @@
+// Package config holds 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`.
+package config
+
+import (
+	"os"
+	"path"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Config is read once at startup and never mutated, so it needs no locking.
+type Config struct {
+	// How often the live poller samples vitals + container stats.
+	PollInterval time.Duration
+	// 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.
+	IdleTimeout time.Duration
+
+	// Max concurrent /stats requests against the Docker socket per tick.
+	DockerConcurrency int
+	DockerSocket      string
+
+	// Storage walk. Roots are "label=path" or just "path".
+	StorageRoots    []string
+	StorageInterval time.Duration
+	// Absolute container-side paths to skip entirely. Their bytes vanish from
+	// the totals, so only exclude things you truly don't want counted.
+	StorageExclude   []string
+	StorageMinRescan time.Duration
+
+	// Tree pruning, to keep the JSON the phone downloads small.
+	TreeDepth int
+	// Children smaller than this fraction of their parent are folded into an
+	// aggregate node rather than shipped individually.
+	TreeMinFraction float64
+	TreeMaxChildren int
+
+	Host string
+	Port int
+
+	// Serve web assets from this directory instead of the ones baked into the
+	// binary. Only useful when iterating on the frontend.
+	WebDir string
+}
+
+// Root is one labelled entry from StorageRoots.
+type Root struct {
+	Label string
+	Path  string
+}
+
+// Roots expands the "label=path" entries. A bare path is labelled with its
+// own basename.
+func (c Config) Roots() []Root {
+	out := make([]Root, 0, len(c.StorageRoots))
+	for _, entry := range c.StorageRoots {
+		label, p, found := strings.Cut(entry, "=")
+		if !found || p == "" {
+			p = label
+			if base := path.Base(strings.TrimRight(label, "/")); base != "" && base != "." {
+				label = base
+			}
+		}
+		out = append(out, Root{Label: label, Path: p})
+	}
+	return out
+}
+
+// Load reads the environment. Unparseable values fall back to the default
+// rather than refusing to start — a typo in one knob should not take the
+// dashboard down.
+func Load() Config {
+	return Config{
+		PollInterval:      envSeconds("KANSHI_POLL_INTERVAL", 5*time.Second),
+		IdleTimeout:       envSeconds("KANSHI_IDLE_TIMEOUT", 30*time.Second),
+		DockerConcurrency: envInt("KANSHI_DOCKER_CONCURRENCY", 8),
+		DockerSocket:      envString("KANSHI_DOCKER_SOCKET", "/var/run/docker.sock"),
+		StorageRoots:      envList("KANSHI_STORAGE_ROOTS", "/=/hostfs,/mnt/data=/mnt/data"),
+		StorageInterval:   envSeconds("KANSHI_STORAGE_INTERVAL", 1800*time.Second),
+		StorageExclude:    envList("KANSHI_STORAGE_EXCLUDE", ""),
+		StorageMinRescan:  envSeconds("KANSHI_STORAGE_MIN_RESCAN", 30*time.Second),
+		TreeDepth:         envInt("KANSHI_TREE_DEPTH", 4),
+		TreeMinFraction:   envFloat("KANSHI_TREE_MIN_FRACTION", 0.005),
+		TreeMaxChildren:   envInt("KANSHI_TREE_MAX_CHILDREN", 24),
+		Host:              envString("KANSHI_HOST", "0.0.0.0"),
+		Port:              envInt("KANSHI_PORT", 8100),
+		WebDir:            envString("KANSHI_WEB_DIR", ""),
+	}
+}
+
+func envString(name, def string) string {
+	if v := os.Getenv(name); v != "" {
+		return v
+	}
+	return def
+}
+
+func envInt(name string, def int) int {
+	v, err := strconv.Atoi(strings.TrimSpace(os.Getenv(name)))
+	if err != nil {
+		return def
+	}
+	return v
+}
+
+func envFloat(name string, def float64) float64 {
+	v, err := strconv.ParseFloat(strings.TrimSpace(os.Getenv(name)), 64)
+	if err != nil {
+		return def
+	}
+	return v
+}
+
+// envSeconds accepts a bare number of seconds, matching the Compose file's
+// plain integers.
+func envSeconds(name string, def time.Duration) time.Duration {
+	v, err := strconv.ParseFloat(strings.TrimSpace(os.Getenv(name)), 64)
+	if err != nil || v <= 0 {
+		return def
+	}
+	return time.Duration(v * float64(time.Second))
+}
+
+func envList(name, def string) []string {
+	raw := os.Getenv(name)
+	if raw == "" {
+		raw = def
+	}
+	var out []string
+	for _, part := range strings.Split(raw, ",") {
+		if p := strings.TrimSpace(part); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}