Обновление по WebHook

Портал документации может обновлять каталоги мгновенно — сразу после push в репозиторий, не дожидаясь следующего цикла обновления по расписанию. Для этого Git-хранилище отправляет порталу webhook-уведомление, и портал сразу загружает изменения затронутого каталога.

Поддерживаемые Git-хранилища

Портал распознает webhook в формате GitHub или GitLab — по заголовку события (X-GitHub-Event или X-Gitlab-Event), подписи или токену и полям тела запроса (адрес репозитория и ветка). Обработка не привязана к конкретному сервису, поэтому подходит любое хранилище, которое умеет отправлять webhook в одном из этих форматов.

GitHub — формат GitHub, поддерживается из коробки.
GitLab и GitLab Self-Hosted — формат GitLab, поддерживается из коробки.
Gitea — отправляет GitHub-совместимый webhook (заголовок X-GitHub-Event и подпись X-Hub-Signature-256), поддерживается. Настраивается так же, как для GitHub.
GitVerse, GitFlic и другие — поддерживаются, если хранилище умеет отправлять webhook в формате GitHub или GitLab. Иначе обновление по webhook недоступно — используйте обновление по расписанию.

Настройка портала

Укажите переменную окружения WEBHOOK_SECRET в файле Docker Compose — секрет, по которому портал проверяет подлинность уведомлений.
Укажите переменную окружения WEBHOOK_TOKEN — токен доступа к репозиторию, по которому портал загружает изменения после уведомления.

WEBHOOK_TOKEN — отдельный токен для обновления по webhook, независимый от AUTO_PULL_TOKEN. Обновление по webhook работает, даже если обновление по расписанию выключено.

Настройка WebHook в GitLab

Откройте репозиторий каталога и перейдите в Settings → Webhooks.
В поле URL укажите https://{адрес портала}/api/webhook.
В поле Secret Token укажите значение WEBHOOK_SECRET.
Отметьте событие Push Events и сохраните webhook.

Настройка WebHook в GitHub

Откройте репозиторий каталога и перейдите в Settings → Webhooks → Add webhook.
В поле Payload URL укажите https://{адрес портала}/api/webhook.
В поле Content-Type выберите application/json.
В поле Secret укажите значение WEBHOOK_SECRET.
Выберите Just the push event и сохраните webhook.

Портал подгружает изменения только для выбранной ветки. Уведомления о публикации в другие ветки будут проигнорированы

Docker Compose

Один экземпляр портала с приемом webhook и настроенным обновлением по расписанию:

services:
    docportal:
        image: docker.io/gramax/docportal:latest
        container_name: docportal
        restart: unless-stopped
        ports:
            - "80:80"
        environment:
            - WEBHOOK_SECRET=${WEBHOOK_SECRET}
            - WEBHOOK_TOKEN=${WEBHOOK_TOKEN}
            - AUTO_PULL_TOKEN=${AUTO_PULL_TOKEN}
            - AUTO_PULL_INTERVAL=180
        volumes:
            - ./gramax:/app/data

Чтобы каталоги обновлялись только по webhook, без обновления по таймингу, не указывайте AUTO_PULL_TOKEN и AUTO_PULL_INTERVAL — достаточно WEBHOOK_SECRET и WEBHOOK_TOKEN.

Несколько экземпляров портала

Если несколько экземпляров портала работают с одними и теми же каталогами, например на общем диске, укажите на основном экземпляре переменную окружения WEBHOOK_PEERS — список адресов остальных экземпляров через запятую. Когда основной экземпляр меняет каталог на диске, он уведомляет остальные, и они приводят свое состояние в соответствие с диском.

Уведомление отправляется после любого изменения каталога: загрузки изменений по webhook, клонирования, синхронизации, переключения ветки, отмены изменений, удаления ветки или удаления каталога. Получив уведомление, экземпляр перечитывает каталог с диска:

каталог есть на диске — экземпляр перечитывает его (или добавляет, если каталога еще не было);
каталога нет на диске — экземпляр убирает его из памяти.

Параметры обновления по расписанию укажите только на одном экземпляре. Остальные экземпляры получают изменения через уведомления — это исключает конфликты при одновременной загрузке.

Любой экземпляр также принимает запрос POST /api/webhook/refresh/{название каталога} с заголовком X-Webhook-Token: {WEBHOOK_SECRET} — экземпляр приведет каталог в соответствие с диском без загрузки из репозитория. Это полезно после переключения ветки, синхронизации или удаления каталога, выполненных другим процессом.

Пример с двумя экземплярами на общем диске — основной загружает изменения и уведомляет реплику, реплика только перечитывает каталог с диска:

services:
    docportal-primary:
        image: docker.io/gramax/docportal:latest
        container_name: docportal-primary
        restart: unless-stopped
        ports:
            - "80:80"
        environment:
            - WEBHOOK_SECRET=${WEBHOOK_SECRET}
            - WEBHOOK_TOKEN=${WEBHOOK_TOKEN}
            - WEBHOOK_PEERS=http://docportal-replica
        volumes:
            - catalogs:/app/data

    docportal-replica:
        image: docker.io/gramax/docportal:latest
        container_name: docportal-replica
        restart: unless-stopped
        ports:
            - "8080:80"
        environment:
            - WEBHOOK_SECRET=${WEBHOOK_SECRET}
        volumes:
            - catalogs:/app/data

volumes:
    catalogs:

Webhook от Git-хранилища настраивается на основной экземпляр. Реплике не нужен WEBHOOK_TOKEN — она не загружает изменения сама, но WEBHOOK_SECRET должен совпадать с основным, чтобы реплика приняла уведомление о перечитывании.

Обновление по расписанию

Передача контента через API