docs: add Debian runtime notes

README.md

@@ -4,6 +4,8 @@ This repository contains the core server files and configurations. It includes f
 
 **For installation and configuration, see [instructions](#installationconfiguration) below.**
 
+Operational Debian/Linux documentation lives under [docs](docs/README.md).
+
 ---
 
 ## 📋 Changelog
@@ -55,6 +57,11 @@ This tutorial will be showing how to install in both FreeBSD and Windows environ
 
 For the Debian runtime used in production, the repository now also contains versioned `systemd` deployment files under [deploy/systemd](deploy/systemd/README.md).
 
+Additional operational notes:
+
+- [Debian Runtime](docs/debian-runtime.md)
+- [Healthchecks](docs/healthchecks.md)
+
 Example installation:
 
 ```bash

docs/README.md

@@ -0,0 +1,15 @@
+# Docs
+
+This directory contains the Debian/Linux-first operational documentation for the serverfiles repository.
+
+Current documents:
+
+- [Debian Runtime](debian-runtime.md)
+- [Healthchecks](healthchecks.md)
+
+Suggested next additions:
+
+- database/bootstrap notes
+- deployment workflow
+- rollback procedure
+- configuration/secrets contract

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.

docs/healthchecks.md

@@ -0,0 +1,88 @@
+# Healthchecks
+
+This repository contains the operational wrapper for the headless login healthcheck. The underlying smoke client lives in `m2dev-server-src`.
+
+## What Exists
+
+Source repository:
+
+- `tests/login_smoke.cpp`
+- binary target: `metin_login_smoke`
+
+Runtime repository:
+
+- `deploy/healthcheck/metin-login-healthcheck.sh`
+
+Installed on the VPS:
+
+- `/usr/local/sbin/metin-login-healthcheck`
+
+## What The Headless Login Check Verifies
+
+The check performs the real two-step Metin login flow without a GUI client:
+
+1. Connect to the auth socket.
+2. Complete the secure handshake.
+3. Send login credentials.
+4. Receive `AUTH_SUCCESS` and the login key.
+5. Open a second connection to the channel socket.
+6. Complete the secure handshake again.
+7. Send `LOGIN2` with `login` + `login_key`.
+8. Verify `EMPIRE`.
+9. Verify `LOGIN_SUCCESS4`.
+
+This is an end-to-end login verification, not just a TCP port check.
+
+## How The Wrapper Works
+
+`metin-login-healthcheck.sh` does the following:
+
+- creates a temporary account in MariaDB
+- runs `metin_login_smoke`
+- verifies a successful auth + channel login
+- deletes the temporary account on exit
+
+It is intended for manual admin use on the VPS.
+
+## Usage
+
+On the VPS:
+
+```bash
+ssh mt2
+/usr/local/sbin/metin-login-healthcheck
+```
+
+The smoke binary can also be run directly:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev \
+  /home/mt2.jakubkadlec.dev/metin/build/server-src/bin/metin_login_smoke \
+  173.249.9.66 11000 11011 <login> <password>
+```
+
+Or with password passed through the environment:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev env METIN_LOGIN_SMOKE_PASSWORD='<password>' \
+  /home/mt2.jakubkadlec.dev/metin/build/server-src/bin/metin_login_smoke \
+  173.249.9.66 11000 11011 <login> --password-env=METIN_LOGIN_SMOKE_PASSWORD
+```
+
+## Security Notes
+
+This does not open a new public network surface. It is a local operational tool.
+
+Current guardrails:
+
+- no new listening port
+- root-only installed wrapper (`/usr/local/sbin/metin-login-healthcheck`, mode `700`)
+- temporary credentials
+- cleanup trap removes the test account
+- wrapper passes the password through environment instead of command-line plaintext
+- secrets are not committed to git
+
+Remaining trust boundary:
+
+- anyone with effective root access can still inspect or run the check
+- therefore this tool assumes root is already trusted