ops: add channel inventory and metinctl

2026-04-14 13:14:37 +02:00
parent 69066cc428
commit 78518daed0
10 changed files with 674 additions and 52 deletions
--- a/docs/server-management.md
+++ b/docs/server-management.md
@@ -0,0 +1,97 @@
+# Server Management
+
+This document describes the current Debian-side control plane for the production Metin runtime.
+
+## Inventory
+
+The channel topology now lives in one versioned file:
+
+- `deploy/channel-inventory.json`
+
+It defines:
+
+- auth and DB listener ports
+- channel ids
+- per-core public ports and P2P ports
+- whether a channel is public/client-visible
+- whether a special channel should always be included by management tooling
+
+This inventory is now the source used by:
+
+- `channel_inventory.py`
+- `channels.py` compatibility exports
+- `install.py`
+- `deploy/systemd/install_systemd.py`
+- `metinctl`
+
+## metinctl
+
+The Debian deployment installs:
+
+- `/usr/local/bin/metinctl`
+
+`metinctl` is a lightweight operational CLI for:
+
+- viewing inventory
+- listing managed units
+- checking service status
+- listing declared ports
+- restarting the whole stack or specific channels/instances
+- viewing logs
+- running the root-only headless healthcheck
+
+## Examples
+
+Show inventory:
+
+```bash
+metinctl inventory
+```
+
+Show current unit state:
+
+```bash
+metinctl status
+```
+
+Show declared ports and whether they are currently listening:
+
+```bash
+metinctl ports --live
+```
+
+Restart only channel 1 cores:
+
+```bash
+metinctl restart channel:1
+```
+
+Restart one specific game instance:
+
+```bash
+metinctl restart instance:channel1_core2
+```
+
+Tail auth logs:
+
+```bash
+metinctl logs auth -n 200 -f
+```
+
+Run the end-to-end healthcheck:
+
+```bash
+metinctl healthcheck
+```
+
+## systemd installer behavior
+
+`deploy/systemd/install_systemd.py` now uses the same inventory and installs `metinctl`.
+
+It also reconciles enabled game instance units against the selected channels:
+
+- selected game units are enabled
+- stale game units are disabled
+- if `--restart` is passed, stale game units are disabled with `--now`
+
+This makes channel enablement declarative instead of depending on whatever happened to be enabled previously.