# 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`.