docs: expand operational runbooks

2026-04-14 09:03:08 +02:00
parent 6c744ee323
commit 7f4233402a
5 changed files with 394 additions and 4 deletions
--- a/docs/deploy-workflow.md
+++ b/docs/deploy-workflow.md
@@ -0,0 +1,165 @@
+# Deploy Workflow
+
+This document describes the current Debian deployment workflow used on the VPS.
+
+## Repositories And Responsibilities
+
+There are two separate repositories involved in a production deploy:
+
+- `m2dev-server-src`: source code, build system, smoke tests, login smoke utility
+- `m2dev-server`: runtime files, configs, quests, systemd deployment assets
+
+In practice:
+
+- source changes are built from `m2dev-server-src`
+- runtime files are synchronized from `m2dev-server`
+- the live instance runs from `~/metin/runtime/server`
+
+## Current VPS Helper Scripts
+
+The current production VPS also has local host-side helper scripts under:
+
+```text
+/home/mt2.jakubkadlec.dev/metin/deploy/
+```
+
+Current helpers:
+
+- `build-server.sh`
+- `sync-runtime.sh`
+- `compile-quests.sh`
+- `install-runtime.sh`
+
+These are currently VPS-local operational wrappers. They are useful, but they are not yet versioned in this repository.
+
+## Common Deploy Paths
+
+Source repository:
+
+```text
+/home/mt2.jakubkadlec.dev/metin/repos/m2dev-server-src
+```
+
+Runtime repository:
+
+```text
+/home/mt2.jakubkadlec.dev/metin/repos/m2dev-server
+```
+
+Build directory:
+
+```text
+/home/mt2.jakubkadlec.dev/metin/build/server-src
+```
+
+Live runtime:
+
+```text
+/home/mt2.jakubkadlec.dev/metin/runtime/server
+```
+
+## Standard Deploy Sequence
+
+### 1. Update repositories
+
+```bash
+ssh mt2
+sudo -iu mt2.jakubkadlec.dev git -C ~/metin/repos/m2dev-server-src pull --ff-only
+sudo -iu mt2.jakubkadlec.dev git -C ~/metin/repos/m2dev-server pull --ff-only
+```
+
+### 2. Build source
+
+Equivalent manual build:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev \
+  cmake -S ~/metin/repos/m2dev-server-src \
+        -B ~/metin/build/server-src \
+        -G Ninja
+
+sudo -iu mt2.jakubkadlec.dev \
+  cmake --build ~/metin/build/server-src --parallel "$(nproc)"
+```
+
+Current VPS wrapper:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev ~/metin/deploy/build-server.sh
+```
+
+### 3. Synchronize runtime files
+
+Equivalent manual sync:
+
+- copy runtime tree from `repos/m2dev-server`
+- exclude generated runtime state
+- install built `game`, `db`, `qc` into the live runtime
+
+Current VPS wrapper:
+
+```bash
+sudo -iu mt2.jakubkadlec.dev ~/metin/deploy/sync-runtime.sh
+```
+
+### 4. Compile quests
+
+```bash
+sudo -iu mt2.jakubkadlec.dev ~/metin/deploy/compile-quests.sh
+```
+
+This runs:
+
+```bash
+cd ~/metin/runtime/server/share/locale/english/quest
+python3 make.py
+```
+
+### 5. Restart services
+
+```bash
+systemctl restart metin-server.service
+```
+
+### 6. Verify runtime
+
+Recommended checks:
+
+```bash
+systemctl status metin-server.service --no-pager
+ss -ltnp | rg ':(9000|11000|11011|11012|11013|11991) '
+/usr/local/sbin/metin-login-healthcheck
+```
+
+## When A Full Rebuild Is Needed
+
+Rebuild `m2dev-server-src` when:
+
+- C++ code changed
+- CMake changed
+- smoke/login test utility changed
+
+Runtime sync only may be enough when:
+
+- configs changed
+- quest files changed
+- locale data changed
+- runtime assets changed
+
+## When systemd Must Be Reinstalled
+
+Re-run the systemd installer when files under `deploy/systemd/` change:
+
+```bash
+python3 deploy/systemd/install_systemd.py \
+  --user mt2.jakubkadlec.dev \
+  --group mt2.jakubkadlec.dev \
+  --runtime-root /home/mt2.jakubkadlec.dev/metin/runtime/server \
+  --channel 1 \
+  --channel 99 \
+  --restart
+```
+
+## Recommended Future Improvement
+
+The current VPS-local helper scripts should eventually be moved into a versioned, reviewable deploy workflow in the repository, or replaced with a single documented deployment entrypoint.