add README.md

README.md

+# epm-docker-test
+
+Небольшая CLI-утилита для быстрого запуска `epm play` в одноразовом Docker-контейнере.
+
+Скрипт:
+- нормализует имя целевой системы в docker image;
+- берёт `eepm` из локального каталога или из builder64;
+- сначала пытается использовать локальный Docker;
+- если локальный Docker недоступен, переключается на `ssh` и запускает Docker под другим пользователем;
+- сохраняет лог и печатает краткий итог выполнения.
+
+## Требования
+
+- `bash`
+- `docker` для локального запуска
+- `ssh` для fallback/remote-режима
+- каталог `eepm`, в котором есть `bin/eepm`
+
+## Быстрый старт
+
+Запуск из локального каталога `eepm`:
+
+```bash
+./epm-docker-test.sh ayugram fedora
+```
+
+Запуск с явным путём к `eepm`:
+
+```bash
+./epm-docker-test.sh --eepm-dir /srv/user/Projects/eepm ayugram fedora
+```
+
+Запуск с builder64-источником:
+
+```bash
+./epm-docker-test.sh --eepm-source builder64 --builder-user user ayugram fedora
+```
+
+Принудительный remote-режим:
+
+```bash
+./epm-docker-test.sh --remote ayugram fedora
+```
+
+## Формат команды
+
+```bash
+./epm-docker-test.sh [options] play <app> <system>
+./epm-docker-test.sh [options] <app> <system>
+```
+
+Сейчас поддерживается только команда `play`.
+
+## Аргументы
+
+- `<app>`: имя приложения для `epm play`
+- `<system>`: целевая система или docker image
+
+Примеры нормализации `<system>`:
+
+- `fedora` -> `fedora:latest`
+- `fedora:43` -> `fedora:43`
+- `Fedora/43` -> `fedora:43`
+
+## Опции
+
+- `--mode <auto|local|remote>`: режим запуска
+- `--remote`: то же, что `--mode remote`
+- `--local`: то же, что `--mode local`
+- `--remote-host <host>`: ssh host для fallback/remote
+- `--remote-user <user>`: ssh user для fallback/remote
+- `--eepm-source <local|builder64>`: источник дерева `eepm`
+- `--eepm-dir <path>`: явный путь к каталогу `eepm`
+- `--builder-user <user>`: пользователь для builder64-источника
+- `--builder-path <path>`: явный builder64-путь вместо дефолта
+- `--log-root <path>`: каталог для логов
+
+## Источник eepm
+
+### local
+
+По умолчанию используется `local`.
+
+Если `--eepm-dir` не задан, скрипт считает, что текущее `pwd` и есть корень каталога `eepm`.
+
+Проверяется наличие:
+
+```text
+bin/eepm
+```
+
+### builder64
+
+Если выбран `--eepm-source builder64`, то по умолчанию используется путь:
+
+```text
+/srv/<builder-user>/Projects/eepm
+```
+
+Если `--builder-user` не задан, берётся текущий пользователь.
+
+Если `--builder-path` задан, используется он.
+
+## Как работает запуск
+
+### auto
+
+Режим по умолчанию.
+
+Порядок такой:
+
+1. Проверка доступности локального Docker.
+2. Если локальный Docker доступен, контейнер запускается локально.
+3. Если локальный Docker недоступен, запуск идёт через `ssh`.
+
+### remote
+
+В remote-режиме скрипт подключается по `ssh` и запускает тот же скрипт на удалённой стороне во внутреннем режиме.
+
+При этом дерево `eepm` не копируется. На удалённую сторону передаётся только путь к нему, поэтому remote-сценарий рассчитан на ту же машину или на окружение с общим файловым деревом, где этот путь виден и локально, и из-под `builder-robot`.
+
+По умолчанию используются:
+
+- host: `builder64`
+- user: `builder-robot`
+
+Эти значения можно переопределить через:
+
+- `--remote-host`
+- `--remote-user`
+
+### Что означает лог раннера
+
+Если в логе видно:
+
+```text
+Runner: ssh -> builder-robot@builder64
+Runner: local docker (inside ssh session, user: builder-robot)
+```
+
+это означает:
+
+- внешний запуск пошёл по `ssh`;
+- уже на удалённой стороне Docker запускается локально для той сессии.
+
+Это нормально.
+
+## Что делает контейнер
+
+Внутри контейнера скрипт:
+
+1. Определяет `os_id` из `/etc/os-release`.
+2. Проверяет наличие `bin/eepm` в примонтированной директории.
+3. Запускает bootstrap через `./bin/eepm`, а не напрямую через пакетный менеджер.
+4. Выполняет:
+
+```bash
+./bin/eepm play --auto <app>
+```
+
+Сейчас bootstrap завязан на семейство системы:
+
+- `altlinux|alt`: `repo set etersoft`, `update`, затем установка `wget glibc-pthread file`
+- `debian|ubuntu`: `update`, затем установка `bash wget ca-certificates coreutils file`
+- все остальные: установка `wget file bash`
+
+## Логи
+
+По умолчанию логи пишутся в:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/epm-docker-test
+```
+
+Если туда писать нельзя, скрипт переключается на временный каталог:
+
+```text
+${TMPDIR:-/tmp}/epm-docker-test
+```
+
+После завершения печатается путь к `run.log`.
+
+При ошибке скрипт дополнительно выводит короткую выборку критичных строк из лога.
+
+## Типовые сценарии
+
+Запустить локально, если Docker доступен:
+
+```bash
+./epm-docker-test.sh ayugram fedora
+```
+
+Запустить удалённо под builder-robot, но с явной директорией `eepm`:
+
+```bash
+./epm-docker-test.sh --remote --eepm-dir /srv/<user>/Projects/eepm ayugram fedora
+```
+
+Запустить с builder64-источником:
+
+```bash
+./epm-docker-test.sh --eepm-source builder64 --builder-user <user> ayugram Fedora/43
+```
+
+## Ограничения текущей версии
+
+- поддерживается только `epm play`
+- нет отдельного режима для копирования локального дерева на удалённый host; remote-режим ожидает, что удалённая сторона видит то же дерево по тому же пути
+- источник `local` ожидает либо запуска скрипта из корня `eepm`, либо передачи `--eepm-dir`