init

README.md

@@ -0,0 +1,42 @@
+# Minecraft Server Live Log Viewer
+
+A read-only Axum + Svelte sidecar for `itzg/docker-minecraft-server`. It streams `latest.log` using filesystem events, paginates plain/gzip/tar-gzip history, and permits an IP only after a currently whitelisted player successfully joined from that address.
+
+## Run as a Docker sidecar
+
+1. Copy `compose.example.yml` beside the Minecraft Compose project.
+2. Replace `PUBLIC_ORIGIN`, `TRUSTED_PROXY_CIDRS`, and the external `caddy` network name.
+3. Run `docker compose -f compose.example.yml up -d --build`.
+4. Point Caddy at `log-viewer:8080`; do not publish the viewer port to the host.
+
+The container runs as UID/GID `10001`, uses a read-only root filesystem, drops every capability, does not mount the Docker socket, and mounts the shared Minecraft volume at `/data:ro`.
+
+Example Caddy integration:
+
+```caddyfile
+logs.example.com {
+    reverse_proxy log-viewer:8080
+}
+```
+
+Caddy supplies `X-Forwarded-For`; the service reads it only when the immediate peer belongs to `TRUSTED_PROXY_CIDRS`. Set this CIDR to the actual Caddy Docker network. Direct clients cannot spoof authorization using that header.
+
+## Authorization lifetime
+
+Only successful joins in the current `latest.log` count. Failed, banned, rejected, and archived attempts do not. Associations survive disconnects until the current log is replaced/truncated or the viewer restarts. A whitelist removal revokes access after the watched JSON file is reloaded. This is a lightweight IP-based privacy barrier, not account authentication; NATs, VPNs, dynamic addresses, and IPv6 privacy addresses limit its precision.
+
+## Configuration
+
+Required: `PUBLIC_ORIGIN`. Paths default to `/data`, `/data/logs`, `/data/logs/latest.log`, and `/data/whitelist.json`. The Compose example documents proxy and redaction settings. Resource limits are configurable with `INITIAL_LOG_LINES`, `MAX_HISTORY_LINES_PER_REQUEST`, `ARCHIVE_CACHE_MAX_BYTES`, `ARCHIVE_CACHE_MAX_FILES`, `MAX_ARCHIVE_DECOMPRESSED_BYTES`, `WS_CLIENT_QUEUE_CAPACITY`, and `MAX_WS_CONNECTIONS`.
+
+Malformed startup configuration or an unreadable initial whitelist fails closed. Later malformed whitelist updates retain the last valid snapshot.
+
+## Development and verification
+
+```sh
+cargo test
+cd frontend && npm install && npm test && npm run check && npm run build
+docker build -t minecraft-log-viewer .
+```
+
+No Node runtime, database, Redis service, recurring file poller, Docker API, RCON, or writable Minecraft mount is used in production.