- keep engine and session factory in src/infra/db/session.py - sync delta specs into openspec/specs, add db-migrations spec - update rules, AGENTS.md and run skill for lab 2 storage - fill REPORT.md for the storage part Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
113 lines
5.5 KiB
Markdown
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:lab2 .`
|
|
- **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 в журнале сервиса нет
|