mcp/README.md

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.

The Compose example bind-mounts the host directory log-viewer-config and reads log-viewer-config/ip-whitelist.txt. Put one IP address or CIDR on each line (# comments are supported) to grant an explicit owner override. Mount the directory rather than the individual file: editors commonly save by replacing a file, and an individual Docker file bind mount remains attached to the replaced inode. The file is read after normal player authorization fails on every access attempt, so edits take effect without restarting the viewer. An unreadable or malformed file grants no override.

With RUST_LOG=minecraft_log_viewer=debug,tower_http=info, each API access logs the effective client IP and authorization source. Override checks also log the configured path, complete parsed IP/CIDR list, match/miss result, and read or parse errors. The complete set of IPs authorized through successful joins and the current Minecraft whitelist is logged as allowed_player_ips.

Example Caddy integration:

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. Set optional IP_WHITELIST_FILE to a mounted owner-managed IP/CIDR file. 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

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.