docs: add Debian runtime notes

docs/debian-runtime.md

@@ -0,0 +1,114 @@
+# Debian Runtime
+
+This document describes the current Debian runtime layout used for the production VPS.
+
+## Scope
+
+There are two separate repositories in the deployment:
+
+- `m2dev-server-src`: source code, build system, smoke/login test binary
+- `m2dev-server`: runtime files, configs, quests, systemd deployment files
+
+The server does not run directly from a git checkout. The live instance runs from a separate runtime directory.
+
+## Directory Layout
+
+Current layout on the VPS:
+
+```text
+/home/mt2.jakubkadlec.dev/metin/
+  repos/
+    m2dev-server-src/
+    m2dev-server/
+  build/
+    server-src/
+  runtime/
+    server/
+```
+
+Meaning:
+
+- `repos/m2dev-server-src`: code changes, git history, tests
+- `repos/m2dev-server`: runtime template and deployment assets
+- `build/server-src`: out-of-tree CMake build
+- `runtime/server`: live runtime tree used by `systemd`
+
+## Runtime User
+
+The runtime user is:
+
+```text
+mt2.jakubkadlec.dev
+```
+
+The user owns the runtime tree and build artifacts. Operational wrappers that need direct database access or privileged installation steps are run as `root`.
+
+## Services
+
+The Debian deployment uses direct `systemd` units instead of a custom bash/python supervisor.
+
+Main orchestration unit:
+
+- `metin-server.service`
+
+Sub-units:
+
+- `metin-db.service`
+- `metin-db-ready.service`
+- `metin-auth.service`
+- `metin-game@channel1_core1.service`
+- `metin-game@channel1_core2.service`
+- `metin-game@channel1_core3.service`
+- `metin-game@channel99_core1.service`
+
+Important behavior:
+
+- `metin-db-ready.service` waits until the DB socket is actually listening before `auth` and `game` start
+- clean shutdown exits now return success instead of fake failure codes
+- Linux runtime currently uses `epoll` for fdwatch and a watchdog-thread checkpoint backend
+
+## Ports
+
+Current service ports:
+
+- `9000`: internal DB socket listener
+- `11000`: auth
+- `11011`: channel 1 core 1
+- `11012`: channel 1 core 2
+- `11013`: channel 1 core 3
+- `11991`: channel 99 core 1
+
+Client-facing login flow currently uses:
+
+- auth: `11000`
+- first public channel: `11011`
+
+## Deployment Notes
+
+Typical operational commands:
+
+```bash
+ssh mt2
+systemctl status metin-server
+systemctl restart metin-server
+journalctl -u metin-auth.service -n 100 --no-pager
+```
+
+Rebuild the login smoke utility:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev \
+  cmake --build /home/mt2.jakubkadlec.dev/metin/build/server-src \
+  --target metin_login_smoke
+```
+
+## Security Notes
+
+Current operational stance:
+
+- password SSH login is disabled
+- `root` login is allowed only by SSH key
+- production helper scripts that touch the DB directly are root-only
+- runtime repo and source repo do not store secrets
+
+Do not store production secrets in markdown, `systemd` templates, or git-tracked shell scripts.