# Песочница на сервере Hestia (sandbox.rebonus.ru)

Временное место песочницы (ADR-0012) до площадки этапа 11. Песочница стоит на сервере компании с панелью Hestia, где
работают и другие сайты. Адрес сервера — у владельца продукта.

- `https://sandbox.rebonus.ru` — кабинеты и API;
- `https://console.sandbox.rebonus.ru` — консоль платформы.

## Что на сервере

- **Hestia.**
  - Пользователь `rebonus` без входа по SSH.
  - Сайт `rebonus.ru` — сайт продукта из папки `site/`, его выкладка описана в `site/README.md`. `www.rebonus.ru`
    перенаправляется на `rebonus.ru`.
  - Сайт `sandbox.rebonus.ru` с `console.sandbox.rebonus.ru`, PHP-FPM 8.5 (шаблон `rebonus-PHP-8_5`, см. «Шаблон
    PHP»).
  - Пользователей, сайты, сертификаты и задания cron заводят только командами Hestia `v-*`. Созданное в обход панели
    она не видит и перезаписывает. Другие сайты сервера не трогать.
- **PHP 8.5.**
  - Ставится через `v-add-web-php 8.5`, из того же репозитория, что и другие версии PHP.
  - Расширения `php8.5-gmp` и `php8.5-pgsql` доставлены отдельно: Hestia ставит `pgsql`, только если сама ведёт
    PostgreSQL.
- **PostgreSQL 17.**
  - Из официального репозитория apt.postgresql.org, слушает только localhost.
  - База `rebonus_sandbox`, роли создаёт `db:bootstrap` (ADR-0002).
  - Пароль суперпользователя `postgres` задаётся только на время `db:bootstrap` и снимается.
- **Код.** Лежит в `/home/rebonus/web/sandbox.rebonus.ru/private/sandbox/`:
  - `releases/<коммит>` — релизы;
  - `shared/` — `.env` с правами 600 и `storage`;
  - `current` — ссылка на текущий релиз.

  `public_html` сайта — ссылка на `private/sandbox/current/public`.
- **Планировщик.** Задание cron пользователя `rebonus` в Hestia: каждую минуту `schedule:run`.
  - Задания он выполняет в своём процессе (`Modules\Kernel\Scheduling\InProcess`). Отдельный процесс PHP запускает
    только для фоновых: отправка сообщений и проверка их доставки, отчёты на почту, автосообщения.
  - Раньше каждое задание было своим процессом, и каждый заново загружал платформу — около 0,4 с процессора. Задания
    каждые 5 секунд (outbox, вебхуки) давали 24 таких процесса в минуту. Всего выходило 32 в минуту, около 11 с
    процессора на песочницу и столько же на рабочую платформу.
  - Файловый кеш OPcache для PHP командной строки (0,2 с на запуск вместо 0,4) не включён. Без своей папки PHP 8.5
    не запускается вовсе. Общая папка настроек песочницы и рабочей платформы сделала бы его рискованным, а после
    перевода заданий в процесс планировщика он сберёг бы около 0,6 с в минуту.
  - После перезагрузки сервера посмотрите `scheduled_runs`. Задание, оборванное посреди запуска, держит блокировку
    (см. «Если что-то сломалось»).
- **Очередь.** Служба systemd `rebonus-sandbox-queue` (очереди `default` и `offline`), файл —
  `rebonus-sandbox-queue.service`.
- **pcntl.** На сервере функции pcntl отключены в php.ini для всех версий PHP, а планировщику и очереди они нужны:
  сигналы и тайм-ауты заданий. Поэтому оба запускаются с `PHP_INI_SCAN_DIR=:/etc/php/8.5/rebonus-cli.d`. Файл
  `99-enable-pcntl.ini` в этой папке снимает запрет только для них. Сайт и остальные процессы сервера живут с
  запретом.
- **Почта.** Письма сотрудникам идут через exim сервера (`MAIL_MAILER=sendmail`) от noreply@rebonus.ru. Их подписывает
  DKIM-ключ почтового домена rebonus.ru в Hestia (селектор `mail`). В DNS rebonus.ru нужны записи SPF, DKIM и DMARC
  (добавлены 2026-11-18). Первая выкладка пишет в `.env` `MAIL_MAILER=log`: на новом месте почту включают, когда эти
  записи готовы. sendmail вызывается в режиме `-t` (`MAIL_SENDMAIL_PATH="/usr/sbin/sendmail -t -i"`): в режиме `-bs`
  по умолчанию Laravel здоровается с exim адресом `[127.0.0.1]`, и exim Hestia отказывает — «550 HELO contains an IP
  address and does not match PTR».
  Входящая почта: ящик `hello@rebonus.ru` с сайта продукта только пересылает письма владельцу продукта. Для него в
  DNS нужна запись MX.

## Шаблон PHP `rebonus-PHP-8_5`

С 2026-11-19 песочница и рабочая платформа (`app.rebonus.ru`, `deploy/production-hestia`) работают на своём шаблоне
PHP-FPM в Hestia: `/usr/local/hestia/data/templates/web/php-fpm/rebonus-PHP-8_5.tpl`. Это копия стандартного
`PHP-8_5` без строки `php_admin_value[open_basedir]`.

- **Зачем.** С `open_basedir` PHP отключает свой кеш путей (realpath cache) и на каждом запросе заново проверяет тысячи
  файлов платформы.
  - Замер на сервере: ответ занимал 0,65–0,75 с, без ограничения — 0,08–0,14 с.
  - Первый запрос нового процесса PHP (после 10 секунд простоя) — 0,4–0,9 с.
- **Чем платим.** `open_basedir` не дал бы взломанному приложению читать файлы вне своих папок. Что остаётся:
  - у песочницы и рабочей платформы свои пользователи системы;
  - `.env` читает только его владелец;
  - у остальных сайтов сервера ограничение есть.
- **Как сделано** (от root):
  1. `PHP-8_5.tpl` скопирован в `rebonus-PHP-8_5.tpl` без строки `open_basedir`, с комментарием в начале.
  2. Сайты переключены командами Hestia:

     ```bash
     v-change-web-domain-backend-tpl rebonus sandbox.rebonus.ru rebonus-PHP-8_5
     v-change-web-domain-backend-tpl rebonusapp app.rebonus.ru rebonus-PHP-8_5
     ```

  Имя шаблона должно кончаться на `PHP-8_5`: по нему Hestia выбирает версию PHP.
- **Обновления Hestia** свой шаблон не трогают, но и не обновляют. После обновления сравнить его с `PHP-8_5.tpl` и,
  если стандартный изменился, сделать копию заново и повторить обе команды.
- **Выкладка** после переключения `current` перезагружает PHP-FPM: процессы PHP помнят в кеше пути старого релиза.

## Тестовый магазин kzla

Заведён один раз через Management API, как это делает `sdk/php/examples/quickstart.php`:
- партнёр Korzilla с клиентом OAuth на все скоупы;
- мерчант «Тестовый магазин kzla» (`external_id` `kzla-test-1`);
- программа:
  - 5 % баллами;
  - начисленные доступны через день;
  - баллами до 30 % чека;
  - сгорают через 365 дней;
- четыре документа согласий: правила, обработка данных, реклама в SMS и в письмах;
- касса «Сайт kzla» вида `ecommerce` с ключом на скоупы `receipts`, `members`, `balances`.

Ключ кассы и секрет клиента — у владельца продукта, в репозитории их нет.

Сотрудники — отдельные учётные записи. Платформа не даёт оператору консоли состоять в команде партнёра или мерчанта
(ADR-0013). Пароль каждый задаёт сам через «Забыли пароль?».

## Выкладка новой версии

С машины разработчика, из корня репозитория. Нужны Node 22 и `sdk/typescript/node_modules`.

```bash
sha=$(git rev-parse --short HEAD)
composer till:build && composer portal:build
git archive --format=tar.gz -o code-$sha.tar.gz $sha
tar -czf builds-$sha.tar.gz public/till-app public/portal-app
scp code-$sha.tar.gz builds-$sha.tar.gz deploy/sandbox-hestia/deploy.sh root@<сервер>:/root/rebonus-deploy/
ssh root@<сервер> bash /root/rebonus-deploy/deploy.sh $sha /root/rebonus-deploy/code-$sha.tar.gz /root/rebonus-deploy/builds-$sha.tar.gz
```

Скрипт по шагам:
1. распаковывает релиз;
2. ставит зависимости Composer без пакетов разработки;
3. выполняет миграции от владельца схемы;
4. кеширует конфигурацию, маршруты, события и шаблоны;
5. переключает `current`;
6. перезагружает PHP-FPM 8.5, чтобы новый релиз видели все процессы PHP, и перезапускает очередь.

Хранятся три последних релиза.

Первую выкладку запускают с последним аргументом `first`. Тогда скрипт ещё:
- пишет `shared/.env` с новыми секретами — на сервере, не выводя их;
- создаёт роли и базу.

## Если что-то сломалось

- **Задачи планировщика не идут.** Если запуск упал, задачи с `withoutOverlapping` остаются заблокированными до
  суток. Снять блокировки — от `rebonus` с тем же `PHP_INI_SCAN_DIR`:

  ```bash
  php8.5 artisan schedule:clear-cache
  ```
- **Где смотреть.** Журнал — `shared/storage/logs/laravel-<дата>.log`. Последние запуски задач — таблица
  `scheduled_runs`, пульс планировщика и очередей — `platform_heartbeats`.

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

Когда имена видны в DNS (записи ведёт владелец домена):

```bash
v-add-letsencrypt-domain rebonus sandbox.rebonus.ru console.sandbox.rebonus.ru
v-add-letsencrypt-domain rebonus rebonus.ru www.rebonus.ru
```
