minecraft-lab/docs/runtime.md

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:

mkdir -p .tools/local-server
cp server/.env.example .tools/local-server/.env
chmod 600 .tools/local-server/.env

В локальном .env явно задать:

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.

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 и данные

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. После принудительного убийства процесса lock может остаться; удалять только когда соответствующий процесс точно завершён. config проверяет контракт без запуска Docker и без создания runtime/binding. up --wait теперь проверяет Minecraft status query и окно стабильной работы, включая restart loops. Отдельная проверка — scripts/server.sh health; timeout/report/logs описаны в health.md.

Обычный Compose также работает с release payload:

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.