From 0c2e661e55e175082481cc5a15d50fed2eb40c9a Mon Sep 17 00:00:00 2001 From: salmonik Date: Sun, 12 Jul 2026 18:25:06 +0200 Subject: architecture --- docs/adr/0001-rcon-only-interaction.md | 37 ++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/adr/0001-rcon-only-interaction.md (limited to 'docs/adr/0001-rcon-only-interaction.md') diff --git a/docs/adr/0001-rcon-only-interaction.md b/docs/adr/0001-rcon-only-interaction.md new file mode 100644 index 0000000..ec7bb41 --- /dev/null +++ b/docs/adr/0001-rcon-only-interaction.md @@ -0,0 +1,37 @@ +# ADR 0001: RCON-only Minecraft server interaction (no console, no file editing) + +## Status + +Accepted + +## Context + +The webUI needs to interact with the running Minecraft server for several operations: querying player count (dashboard), managing the whitelist, managing OPs, and managing bans. Two primary approaches exist: + +1. **File editing** — Read and write `whitelist.json`, `ops.json`, `banned-players.json` directly on disk. Requires a server restart or `/reload` to apply changes. +2. **RCON** — Send commands over the RCON protocol. Changes apply immediately, no restart needed. Also enables querying server state (`/list`). +3. **Docker stdin/stdout** — Attach to the container's console. Enables log streaming and command input. Requires persistent WebSocket/SSE connection. + +## Decision + +We will use **RCON exclusively** for all webUI-to-server interaction: + +- Player count queries via RCON `/list` +- Whitelist, OP, and ban management via RCON commands (`/whitelist add`, `/op`, `/ban`, etc.) +- No log streaming, no Docker console attachment +- No direct editing of `whitelist.json`, `ops.json`, or other server files +- RCON password is auto-generated per Instance and stored internally + +## Consequences + +### Positive +- Changes apply immediately without server restart +- No WebSocket or SSE infrastructure required +- No log parsing or streaming complexity +- User-facing player management is username-based (users don't need to know UUIDs or JSON structure) +- Simpler codebase: request/response pattern over TCP, not persistent connections + +### Negative +- No server logs visible in the webUI — debugging crashes requires Docker CLI access (but this is a system administration concern, out of scope for the webUI) +- RCON must be enabled and reachable (`enable-rcon=true`, port exposed) for the webUI to function for live Instance operations +- If the Minecraft process crashes inside the container, RCON becomes unreachable and the webUI can only report "crashed — check Docker logs" rather than showing the error -- cgit v1.2.3