# Развёртывание в Docker **Дата:** 2 ноября 2026 · **Статус:** файлы написаны и проверены имитацией; сборка образа и `docker compose up` в среде разработки не запускались (там нет Docker) ## Что входит | Файл | Назначение | |---|---| | `Dockerfile` | Образ сервиса: двухэтапная сборка на `python:3.12-slim`, запуск не от root (пользователь `app`, uid 10001), проверка здоровья `/health` | | `docker/entrypoint.sh` | Точка входа: `serve` (по умолчанию), `migrate`, любая другая команда передаётся в `python -m estimator` | | `docker-compose.yml` | Три сервиса: `db` (PostgreSQL 16 с pgvector), `migrate` (разовое задание), `app` (сервис) | | `.dockerignore` | Не пускает в образ `.env`, тесты, документацию, `.git` | | `.env.example` | Шаблон `.env`: настройки сервиса, переменные compose, веб-интерфейс, обратный прокси | ## Порядок запуска и миграции ``` db становится healthy ─► migrate применяет схему и завершается успешно ─► app запускается ``` - `migrate` ждёт базу (`wait-db`, до 60 секунд), выполняет `alembic upgrade head` и выходит. `app` стартует только при коде возврата 0 (`service_completed_successfully`): **если миграция не прошла, сервис не запускается**. - Миграции вынесены в отдельное задание, а не в запуск самого сервиса: при нескольких копиях сервиса они не будут применяться одновременно. - Миграция повторяема: повторный запуск ничего не меняет. Она создаёт расширение `vector` (поэтому образ базы `pgvector/pgvector:pg16`, а пользователь базы должен быть суперпользователем, как в compose). - Для одного контейнера без compose есть `MIGRATE_ON_START=true`: тогда `serve` сначала ждёт базу и применяет миграции, при сбое любого шага сервис не стартует. - Проверка готовности базы в compose идёт по TCP (`pg_isready -h 127.0.0.1`): временный сервер первого запуска слушает только сокет, и проверка по сокету могла бы объявить базу готовой раньше времени. ## Запуск ```bash cp .env.example .env # POSTGRES_PASSWORD, ключ(и) LLM, EST_API__KEYS docker compose up -d --build docker compose logs -f migrate app curl http://localhost:8000/health ``` `POSTGRES_PASSWORD` обязателен: без него compose отказывается стартовать. Пароль должен состоять из букв и цифр, он входит в строку подключения. ## Обновление ```bash git pull && docker compose up -d --build # migrate выполнится перед запуском новой версии сервиса ``` Откат схемы не автоматический: перед обновлением делайте копию базы. ## Резервная копия и восстановление ```bash docker compose exec db pg_dump -U estimator -Fc estimator > estimator.dump docker compose exec -T db pg_restore -U estimator -d estimator --clean < estimator.dump ``` ## Администрирование ```bash # пароль для пользователя веб-интерфейса (запрашивается дважды, не короче 12 символов) docker compose run --rm app hash-password # загрузка корпуса аналогов (файл монтируется в контейнер) docker compose run --rm -v "$PWD/refs.csv:/data/refs.csv:ro" app rag import /data/refs.csv --project "Проект" docker compose run --rm app rag stats ``` Хэш пароля содержит знаки `$`. В `.env` значение `EST_WEB__USERS` берите в одинарные кавычки, иначе compose попытается их раскрыть. ## За обратным прокси и HTTPS - Включите `EST_API__PROXY_HEADERS=true` и укажите адреса прокси в `EST_API__FORWARDED_ALLOW_IPS` (никогда `*`, если порт доступен напрямую): иначе ограничитель попыток входа видит адрес прокси вместо адреса клиента. - В образе по умолчанию `EST_ENV=prod`, то есть `config/prod.toml` с `cookie_secure = true`: сессионная cookie отправляется только по HTTPS (на `localhost` современные браузеры это допускают). Для обычного http на другом адресе задайте `EST_WEB__COOKIE_SECURE=false`. - Сервис сам HTTPS не терминирует. ## Что сделано для безопасности Запуск не от root, `cap_drop: ALL`, `no-new-privileges`, база не публикуется на хост, секреты не попадают в образ (`.env` исключён из контекста сборки, в `Dockerfile` нет ключей), пароль базы обязателен, пакеты ставятся только из собранных колёс. Конфигурация и промпты лежат в образе (`/app/config`, `/app/prompts`); чтобы их заменить, смонтируйте свои каталоги поверх. ## Что проверено и что нет Проверено: - колесо собирается и содержит шаблоны, статику и `htmx.min.js`; в зависимостях объявлен `pgvector` (его не хватало, он нужен схеме; теперь тест сверяет все импортируемые пакеты с `pyproject.toml`); - в чистом виртуальном окружении, установленном из колёс (без каталога проекта), команда `migrate` применяет схему на PostgreSQL 16 с pgvector (таблицы, расширение, индекс HNSW), повторный запуск ничего не меняет; - `serve` с `MIGRATE_ON_START=true` на пустой базе применяет миграции и только потом поднимает сервис, который отвечает на запросы; - недоступная база или сломанная миграция останавливают запуск, порт не слушается; - `wait-db` ждёт появления базы и возвращается, когда она создана; - тесты в репозитории проверяют порядок вызовов точки входа (заглушкой вместо `python`), структуру compose (порядок запуска, один образ, обязательный пароль, база не опубликована) и свойства `Dockerfile` (не root, что копируется, нет секретов, `.dockerignore` не исключает нужное). Не проверено (в среде нет Docker): `docker build`, `docker compose up`, размер образа, проверка здоровья внутри контейнера, поведение образа `pgvector/pgvector:pg16` на первом запуске (предполагается, что расширение в нём есть, а пользователь по умолчанию суперпользователь). Первый запуск стоит пройти вручную и посмотреть `docker compose logs migrate`. ## Ограничения - Фоновые расчёты идут внутри процесса: запускайте одну копию `app`. - Нет автоматических резервных копий и срока хранения старых оценок, нет ограничения частоты запросов к API. - Образ не подписывается и не сканируется на уязвимости; версии зависимостей не закреплены (задаются нижними границами в `pyproject.toml`).