Files
estimator/docs/deployment.md
T
2026-11-09 08:43:30 +03:00

8.8 KiB
Raw Blame History

Развёртывание в 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): временный сервер первого запуска слушает только сокет, и проверка по сокету могла бы объявить базу готовой раньше времени.

Запуск

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 отказывается стартовать. Пароль должен состоять из букв и цифр, он входит в строку подключения.

Обновление

git pull && docker compose up -d --build   # migrate выполнится перед запуском новой версии сервиса

Откат схемы не автоматический: перед обновлением делайте копию базы.

Резервная копия и восстановление

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

Администрирование

# пароль для пользователя веб-интерфейса (запрашивается дважды, не короче 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).