first cycle lab release

2026-10-04 00:30:09 +07:00
parent 85f6897365
commit d134daafd8
92 changed files with 5623 additions and 9 deletions
@@ -0,0 +1,107 @@
+# Server runtime — Phase 4
+
+Полный релиз содержит готовый Docker Compose. `scripts/server.sh` управляет
+им локально, проверяя artifact checksums, manifest, pinned Compose и
+подтверждённую Minecraft/loader/image/Java комбинацию. Wrapper требует
+Node/npm dependencies, Docker daemon и локальный Compose из bootstrap.
+Сам payload можно запускать обычным Docker Compose на подготовленном host.
+
+## Первоначальная настройка
+
+Выбрать отдельный server root и готовый full release. Пример для второго
+локального сервера, пока основной работает на 25565:
+
+```bash
+mkdir -p .tools/local-server
+cp server/.env.example .tools/local-server/.env
+chmod 600 .tools/local-server/.env
+```
+
+В локальном `.env` явно задать:
+
+```dotenv
+MC_EULA=TRUE
+MC_MEMORY=2G
+MC_PORT=25566
+MC_BIND_ADDRESS=127.0.0.1
+MC_UID=1000
+MC_GID=1000
+MC_PROJECT_NAME=minecraft-lab-local
+```
+
+`MC_EULA=TRUE` означает ваше принятие https://www.minecraft.net/en-us/eula.
+Для текущего эксперимента оно уже получено. На новом host EULA принять
+самостоятельно. UID/GID выбрать для владельца runtime на host; image
+инициализирует права данных с этими значениями. Оператор должен иметь
+доступ к Docker, server root и локальному `.env`.
+
+Файл использует простые `KEY=value` без кавычек/interpolation. Пока разрешены
+только перечисленные ключи. Его значения имеют приоритет над случайными
+ambient MC_EULA/MEMORY/PORT/UID/GID из shell. Project можно выбрать также
+через `MC_PROJECT_NAME` в shell; он должен оставаться стабильным для этого root.
+
+```bash
+export MC_ROOT="$PWD/.tools/local-server"
+export MC_RELEASE_DIR="$PWD/dist/minecraft-lab-neoforge-spike-0.0.4"
+scripts/server.sh config --quiet
+scripts/server.sh up -d --wait --wait-timeout 600
+scripts/server.sh ps
+scripts/server.sh logs --tail 100
+scripts/server.sh exec -T minecraft mc-health
+```
+
+Пути должны быть абсолютными; cwd не влияет на mounts. `MC_ENV_FILE` может
+выбрать другой абсолютный файл настроек вне immutable release; по умолчанию
+используется `MC_ROOT/.env`. Для второго runtime нужен отдельный стабильный
+project и свободный порт. Wrapper отклоняет project, чьи существующие
+контейнеры подключают другой `/data`.
+
+## Lifecycle и данные
+
+```bash
+scripts/server.sh restart --timeout 120
+scripts/server.sh up -d --wait --wait-timeout 120
+scripts/server.sh stop
+scripts/server.sh create --force-recreate
+scripts/server.sh up -d --wait --wait-timeout 120
+scripts/server.sh down
+```
+
+Restart/create/stop/down относятся к тому же выбранному релизу. `down`
+удаляет контейнер и network, но сохраняет host runtime. Данные не находятся
+в named volume: `MC_ROOT/runtime` монтируется в `/data` read-write.
+Release и его `server/config` монтируются read-only. Онлайн-проверка аккаунтов
+выключена. `MC_BIND_ADDRESS` в host `.env` выбирает IPv4 интерфейс:
+по умолчанию 127.0.0.1; для remote LAN задать 0.0.0.0.
+
+Первая инициализация разрешена только с пустым runtime (или `.gitkeep`).
+В root создаётся `.mcpack-runtime.json`: project и SHA256 manifest выбранного
+релиза. Binding записывается перед запуском и сохраняется даже при его
+неудаче, чтобы повторный up продолжал ту же попытку. Это не active-release
+и не отметка успешного deployment.
+
+Смена релиза/project на связанном runtime и неявное принятие существующего
+мира без binding запрещены. Backup/restore реализованы в Phase 5;
+смена релиза требует будущего deploy workflow. Текущий старый Phase 0 мир управляется `scripts/spike-server.sh`;
+миграция на новый wrapper в Phase 4 не выполняется.
+
+Lifecycle-операции и весь цикл backup используют общую `.mcpack-runtime.lock`
+в server root. Snapshot/recovery procedure — [backups.md](backups.md). После
+принудительного убийства процесса lock может остаться; удалять только когда
+соответствующий процесс точно завершён. `config` проверяет контракт без
+запуска Docker и без создания runtime/binding. `up --wait` теперь проверяет
+Minecraft status query и окно стабильной работы, включая restart loops.
+Отдельная проверка — `scripts/server.sh health`; timeout/report/logs описаны
+в [health.md](health.md).
+
+Обычный Compose также работает с release payload:
+
+```bash
+MC_ROOT=/absolute/server-root MC_RELEASE_DIR=/absolute/full-release \
+  docker compose --project-name minecraft-lab-local \
+  --env-file /absolute/server-root/.env \
+  -f /absolute/full-release/server/compose.yaml up -d --wait
+```
+
+При прямом вызове Compose проверки/binding/lock wrapper не выполняются;
+для локального lifecycle используйте `scripts/server.sh`.