Files
mtusi2026lab4/openspec/specs/container-image/spec.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- carry the lab 3 solution over from mtusi2026lab3-safronov
  (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests,
  bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts,
  Dockerfile, compose, pyproject and uv lock
- merge Makefile, .gitignore and .dockerignore (the lab 3 versions only
  add lines to the skeleton, which is the same in lab 4) and
  .env.example (lab 4 skeleton names listed in the header)
- rename the compose project to mtusi-lab4 and the image to :lab4 so
  the stand does not reuse the lab 3 containers and volumes
- update AGENTS.md for lab 4: current lab, origin commit, contract and
  test files of the new skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:32:33 +03:00

113 lines
5.5 KiB
Markdown

# 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:lab4 .`
- **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 в журнале сервиса нет