> ## Documentation Index
> Fetch the complete documentation index at: https://veriqa.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Локальная проверка интеграции

> Как поднять связку «CMS + Veriqa» на своей машине и какие сложности при этом возникают только локально — в проде именно этих сложностей не будет.

Прогнать интеграцию на ноутбуке до выкатки — разумно. Но почти все трудности локального стенда
порождены самим стендом, а не Veriqa.

<Note>
  **Всё на этой странице — про локальную проверку.** В продакшне, где у Veriqa настоящий домен и
  валидный сертификат, ни одной из этих сложностей нет: боевая схема **проще** локальной.
</Note>

## Сертификат

Самоподписанный сертификат придётся смонтировать внутрь **каждого** контейнера и выполнить
`update-ca-certificates` — иначе PHP-cURL рвёт обмен кода на токены. В проде этого шага нет
вовсе.

<Warning>
  **Системного хранилища доверия хватает не всем.** `update-ca-certificates` кладёт CA туда, куда
  смотрят PHP и Ruby, но не каждый рантайм читает это хранилище. Python-клиенты на `requests`
  (например, модуль OIDC у Odoo) используют собственный бандл `certifi` и продолжают рвать обмен
  кода даже с установленным CA — им нужен `REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt`.
  Правило общее: хранилище доверия своё у каждого рантайма, и проверять надо тот, на котором
  написан клиент, а не тот, на котором работает сайт.
</Warning>

Отдельная засада: **антивирус, перехватывающий TLS**, подменяет самоподписанный сертификат своим
и показывает заглушку «переход на домен с недоверенным сертификатом». Ссылка «продолжить» в такой
заглушке теряет query string — то есть весь OIDC-запрос, — поэтому пройти её нельзя ни мышью, ни
программно. Серверные вызовы это не затрагивает: PHP в контейнере ходит по смонтированному CA и
проблемы не видит.

Рабочий обход, не трогающий настройки безопасности машины: поднять **два HTTPS-эндпоинта** —
один со своим сертификатом для контейнеров, другой с dev-сертификатом, уже доверенным в системе,
для браузера человека.

## Адрес issuer

Три правила:

* **issuer только по https.** На `http://localhost:5200` ядро отвечает отказом даже в
  Development. Обратите внимание: `redirect_uri` по `http` при этом принимается — ограничение
  касается именно адреса issuer;
* **адрес должен резолвиться одинаково** из контейнера и с хоста, иначе `iss` в discovery
  разъедется с тем, что видит браузер;
* **приватный адрес блокируется клиентами.** `host.docker.internal` — приватная сеть, и почти
  каждая система защищается от обращений туда собственным флагом: WordPress режет такие запросы
  через `wp_safe_remote_post()` (лечится настройкой `allow_internal_idp`), Drupal — флагом
  `allow_private_issuer`, Nextcloud — `allow_local_remote_servers`, Discourse —
  `allowed_internal_hosts`, Moodle — `curlsecurityblockedhosts`. В проде адрес публичный, и все
  эти флаги не нужны.

<Warning>
  **Одно исключение, которое в проде не исчезает.** Moodle ограничивает исходящие запросы не
  только по адресу, но и **по порту**: `curlsecurityallowedport` по умолчанию разрешает лишь 443
  и 80. Если ваш issuer слушает нестандартный порт, порт придётся разрешить явно и на боевом
  адресе тоже.
</Warning>

## Мелочи окружения

| Что | Симптом |
| - | - |
| DNS контейнера | пакетные зеркала могут не резолвиться изнутри контейнера; лечится явными DNS в compose |
| Права на каталог приложения | в именованном томе каталог принадлежит root, и Composer от `www-data` в него не пишет |
| `AllowOverride None` в образе `php:apache` | TYPO3 раздаёт фронт через `.htaccess`: главная открывается, а любой человекочитаемый адрес отдаёт 404 **самого Apache** — по виду страницы это и опознаётся |
| Повторный `typo3 setup --create-site` | отрабатывает только на чистой базе; на развёрнутой падает, и сайт-конфигурация не создаётся |

## Почта

Для канала Email локально удобно поднять почтовый приёмник вместо настоящего SMTP: письма никуда
не уходят, а ссылку из письма видно в его веб-интерфейсе.

<Warning>
  На SMTP **без аутентификации** отправка писем срабатывает через раз: соединение переиспользуется
  некорректно, и каждая вторая попытка отдаёт ошибку. Повтор запроса проходит. Это известное
  ограничение, а не следствие вашей конфигурации — см. [Диагностику](/docs/ru/guides/troubleshooting).
</Warning>

Ещё одно: у канала Email есть штатный rate limit — при отладке несколькими запросами подряд вы
увидите `429`. Закладывайте паузу.

## Чего локальный стенд не проверяет

* **доставляемость почты** — SPF, DKIM, DMARC и репутацию домена локальный приёмник не проверяет;
* **поведение вендорских платформ** — Shopify и Wix ходят к Veriqa снаружи, им нужен её
  публичный HTTPS-адрес, см. [SaaS-конструкторы](/docs/ru/integrations/saas-builders);
* **скорость под нагрузкой** — локальные цифры отклика ничего не говорят о проде.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.