Gotcha

Обновление

Перед началом: сделайте резервную копию

Обновление применяет миграции схемы баз данных — это необратимо (обратных миграций «на всякий случай» никто не запускает автоматически). Прежде чем обновлять, снимите бэкап и PostgreSQL, и ClickHouse — см. Резервное копирование и восстановление. Не пропускайте этот шаг, даже если обновление кажется мелким.

Обычное обновление (один сервер, режим --mode=all)

Если вы используете штатный docker-compose.yml как есть (одна реплика приложения, --mode=all) — это самый частый случай для self-hosted установки:

cd gotcha   # папка с docker-compose.yml
git pull
docker compose build
docker compose up -d

Разбор:

  1. git pull — подтягивает новый код из репозитория.
  2. docker compose build — пересобирает образ приложения gotcha с обновлённым кодом (Postgres/ClickHouse используют готовые официальные образы, их специально пересобирать не нужно — Compose скачает нужную версию сам, если она изменилась в docker-compose.yml).
  3. docker compose up -d — пересоздаёт контейнер gotcha из нового образа. При старте (это стандартное поведение, GOTCHA_AUTO_MIGRATE=true по умолчанию) приложение само применяет недостающие миграции схемы к PostgreSQL и ClickHouse, прежде чем начать принимать запросы — отдельно ничего делать не нужно.

Если хотите обновить только образ без пересборки из исходников (например, вы используете готовый образ из реестра, а не собираете из git) — используйте docker compose pull вместо docker compose build.

Что означает автоматическое применение миграций

По умолчанию (GOTCHA_AUTO_MIGRATE=true) при каждом старте приложение проверяет версию схемы в базе и, если она отстаёт от версии, «зашитой» в бинарник, применяет недостающие миграции автоматически, прежде чем открыть порт. Это удобно для типовой установки «один сервер, один процесс» — обновление сводится к трём командам выше.

Раздельное применение миграций (несколько реплик приложения)

Если вы запускаете несколько процессов gotcha одновременно (например, отдельно --mode=ingest и --mode=web, или несколько реплик за балансировщиком — сценарий продвинутой эксплуатации, выходящий за рамки штатного docker-compose.yml), автоматические миграции при старте каждой реплики опасны: несколько процессов могут попытаться применить миграции одновременно. Для этого случая:

  1. Установите GOTCHA_AUTO_MIGRATE=false для всех реплик.

  2. Перед запуском реплик выполните миграции один раз, отдельным разовым запуском бинарника с GOTCHA_AUTO_MIGRATE=true (или вообще без переопределения — это дефолт), например:

    docker compose run --rm \
  -e GOTCHA_AUTO_MIGRATE=true \
  gotcha /bin/sh -c "true"

    На практике для этого достаточно один раз запустить обычный контейнер gotcha (в любом режиме) с GOTCHA_AUTO_MIGRATE=true — миграции применяются в самом начале старта, до открытия HTTP-порта, независимо от --mode.

  3. После этого запустите (или перезапустите) все реплики с GOTCHA_AUTO_MIGRATE=false — они проверят, что схема БД совпадает со встроенной версией, и откажутся стартовать, если это не так (это защита от «тихого» приёма данных в устаревшую схему — лучше явный отказ при старте, чем молчаливые ошибки на каждой вставке).

Для штатного docker-compose.yml из этого репозитория (один сервис gotcha в режиме all) раздельные миграции не нужны — используйте обычный сценарий обновления выше.

Откат назад

Миграции схемы в Gotcha написаны как «вперёд» — рассчитывать на автоматический безопасный откат схемы назад не стоит. Если после обновления что-то пошло не так:

  1. Приложение откатить просто — переключитесь на предыдущий коммит/тег и пересоберите:
    git checkout <предыдущий-тег-или-коммит>
docker compose build
docker compose up -d
    Это откатывает только код приложения. Если новая версия уже успела применить новые миграции схемы к базе — старый бинарник может не заработать с новой схемой (несовместимость в обратную сторону) или, если совместимость сохранена, поработает штатно.
  2. Если откат кода без отката схемы не работает (старая версия явно требует старую схему — при старте вы увидите ошибку вида «версия схемы впереди встроенной») — самый надёжный путь отката: восстановить резервную копию, снятую перед обновлением (см. Резервное копирование и восстановление), и поднять на ней предыдущую версию приложения.

Именно поэтому шаг «сделайте бэкап перед обновлением» в начале этой страницы — не формальность, а единственный надёжный путь назад.

Проверка после обновления

docker compose ps
curl -sf http://localhost:59080/healthz

docker compose ps — все контейнеры должны быть Up (postgres/clickhouse — Up (healthy)). /healthz должен вернуть {"clickhouse":"ok","postgres":"ok"} с кодом 200. Дополнительно посмотрите логи на предмет ошибок при старте:

docker compose logs --tail=100 gotcha

Строка applying migrations, за которой не следует сообщение об ошибке — миграции прошли успешно. Затем откройте интерфейс в браузере и убедитесь, что вы видите свои организации, проекты и данные.

Что дальше