# container-image Specification ## Purpose Образ сервиса: как он собирается из исходников и что в нём есть. Сборка воспроизводима из чистого clone, версии закреплены, процесс работает без привилегий, конфиги и секреты в образ не попадают. ## Requirements ### Requirement: Сборка из чистого clone `docker build` в корне свежего clone SHALL собирать образ без предварительных шагов: без `make env_setup`, без `config.toml` и `.env`. Зависимости SHALL устанавливаться строго по `uv.lock`. Если lock не соответствует `pyproject.toml`, сборка MUST завершаться ошибкой, а не пересчитывать версии. #### Scenario: Свежий clone - **WHEN** в новом clone репозитория выполняется `docker build -t mtusi-messenger:lab6 .` - **THEN** образ собирается без ошибок #### Scenario: Устаревший lock - **WHEN** в `pyproject.toml` добавлена зависимость, а `uv.lock` не обновлён - **THEN** сборка завершается ошибкой проверки lock ### Requirement: Закреплённые версии Базовые образы и инструменты сборки SHALL указываться явной версией и digest. Плавающие теги (`latest`, `3.12-slim` и подобные) MUST NOT использоваться. #### Scenario: Проверка Dockerfile - **WHEN** проверяющий читает строки `FROM` и `COPY --from` в `Dockerfile` - **THEN** каждая ссылка на образ содержит версию с патч-номером и `@sha256:` ### Requirement: Непривилегированный пользователь Процесс сервиса SHALL работать не от root. Код приложения и зависимости MUST NOT быть доступны этому пользователю на запись. #### Scenario: UID процесса - **WHEN** в работающем контейнере выполняется `id -u` - **THEN** результат не равен 0 #### Scenario: Код только на чтение - **WHEN** пользователь контейнера пытается записать файл в каталог с кодом приложения - **THEN** запись отклоняется с ошибкой доступа ### Requirement: Состав образа Образ SHALL содержать только то, что нужно для работы сервиса и применения миграций: интерпретатор, зависимости времени выполнения, исходники `src/`, каталог миграций и конфигурацию инструмента миграций. В образе MUST NOT быть `config.toml`, `.env`, публичных и собственных тестов, контрактов, файлов `.claude` и `openspec`, а также инструментов сборки: uv и компиляторов. #### Scenario: Нет конфигов и лишних каталогов - **WHEN** в образе просматривается рабочий каталог приложения - **THEN** в нём есть только исходники, миграции с их конфигурацией и окружение зависимостей, а `config.toml` и `.env` отсутствуют #### Scenario: Нет uv в runtime - **WHEN** в контейнере запрашивается `uv` - **THEN** команда не найдена #### Scenario: Миграции из образа - **WHEN** контейнер из этого образа запускается командой применения миграций с настройками подключения к Postgres - **THEN** миграции применяются без доступа к исходникам на хосте ### Requirement: Сервер — основной процесс контейнера Процессом с PID 1 SHALL быть сам сервер (`python -m src`), без оболочки и без `uv run` между Docker и сервером. Так сигналы остановки доходят до сервера напрямую. #### Scenario: PID 1 - **WHEN** в работающем контейнере читается командная строка процесса 1 - **THEN** это `python -m src` ### Requirement: Healthcheck образа Образ SHALL объявлять healthcheck, который проверяет `GET /health/ready` на внутреннем порту сервиса. Healthcheck MUST работать и без compose, при запуске голым `docker run`. #### Scenario: Контейнер становится healthy - **WHEN** контейнер запущен и сервис завершил старт - **THEN** `docker inspect` показывает состояние здоровья `healthy` до окончания `start_period` #### Scenario: Healthcheck не шумит в логах - **WHEN** healthcheck отрабатывает несколько раз - **THEN** итоговых записей о запросах к health в журнале сервиса нет ### Requirement: Worker на образе приложения Worker SHALL запускаться из того же образа, что и API, своей командой. Процессом с PID 1 контейнера worker SHALL быть сам worker (`python -m src.worker`), без оболочки между Docker и им. Декодер изображений SHALL входить в образ зависимостью времени выполнения из `uv.lock`, без компиляторов в runtime. Healthcheck образа проверяет HTTP и worker не подходит: у контейнера worker он SHALL быть выключен, и живость видна по журналу. Реплики API и сам процесс worker MUST NOT загружать декодер изображений в память: его загружает только дочерний процесс обработки (`attachment-processing`, «Лимиты обработки»). #### Scenario: PID 1 worker - **WHEN** в работающем контейнере worker читается командная строка процесса 1 - **THEN** это `python -m src.worker`, а `docker inspect` не показывает у контейнера проверки здоровья #### Scenario: Декодер в образе - **WHEN** в образе, собранном из чистого clone, импортируется декодер изображений и запрашивается версия - **THEN** импорт проходит, версия совпадает с `uv.lock`, поддержка WebP есть, а `uv` и компиляторов в образе нет #### Scenario: Декодера нет в процессе API - **WHEN** в работающей реплике API и в процессе 1 контейнера worker проверяются загруженные модули - **THEN** декодера изображений среди них нет ### Requirement: Relay на образе приложения Relay SHALL запускаться из того же образа, что и API, своей командой. Процессом с PID 1 контейнера relay SHALL быть сам relay (`python -m src.relay`), без оболочки между Docker и им. Healthcheck образа проверяет HTTP и relay не подходит: у контейнера он SHALL быть выключен, живость видна по журналу. #### Scenario: PID 1 relay - **WHEN** в работающем контейнере relay читается командная строка процесса 1 - **THEN** это `python -m src.relay`, а `docker inspect` не показывает у контейнера проверки здоровья