use-deploy

Informational, not binding. Know a better way for the case in front of you — do it your way and say so. You are trusted with the creative work on this project.

1. Сначала спроси: а нужна ли сборка

Половина «деплоев» здесь не нужна вовсе. Начинать с этого вопроса дешевле, чем ждать сборку.

2. Один путь на сервер

Транспорт — четыре скрипта в scripts/server/ (их таблица — в CLAUDE.md, раздел «The server»). Свой ssh/scp не изобретать: у путей проекта есть скобки (app/[lang]/(publicLayer)/…), и каждая — лишний слой экранирования, на котором команда рвётся молча.

Обычный день — одна команда:

bash scripts/server/deploy.sh app/[lang]/page.tsx lib/products

Доставка → замок → сборка с меткой коммита → pm2 reload → сверка. Без путей — только пересборка. Отдельные скрипты нужны редко: copy.sh — положить и ничего не собирать, run.sh — посмотреть что-то на сервере, status.sh — прочитать состояние, ничего не меняя.

3. 🔒 Два режима сборки — и владелец видит разницу

Выбор автоматический, но последствие называй вслух, когда собираешь напрямую: подвал сайта — то, по чему владелец судит, доехала ли работа.

🔒 Секрет решает, КТО собирает, а не КАК ты туда попадёшь. Дверь сборки панели — http://localhost:3002/api/deploy, то есть localhost самого сервера, и добираешься ты до неё по SSH в обоих режимах. FRACTERA_DEPLOY_SECRET без FRACTERA_SSH_* не работает: читается как «канал есть», а его нет. → §6a

4. 🔒 Чем доказывается доставка

Два пруфа из разных плоскостей (закон — в use-testing):

1. commit в /api/health равен твоему хэшу — отвечает именно твоя сборка;
2. status.sh даёт 0 — порт держит pm2 или его потомок, uptime растёт между замерами.

🔒 Лог сборки доказательством не является. «Compiled successfully», «200 OK», «хэш нашёлся в .next» читаются одинаково и когда работа доехала, и когда нет.

🔒 "commit": null в /api/health — сборка шла БЕЗ метки (поймано прогоном 2026-08-22 на живом сервере). Так выглядит ручной npm run build без NEXT_PUBLIC_GIT_COMMIT: приложение работает, а первый пруф недоступен — сказать, какая сборка отвечает, нечем. Лечится пересборкой с меткой; в deploy.sh она ставится сама, поэтому ручной сборки и стоит избегать.

5. Четыре ловушки, каждая уже оплачена

• Код возврата берётся у npm, а не у конвейера. npm run build | tail печатает код tail — то есть всегда ноль. Упавшая по типам сборка так выглядит успешной, а на сервере остаётся старый .next.
• online в pm2 list не значит ничего. Процесс в вечном рестарте выглядит так же; смотри счётчик рестартов и растущий uptime.
• Сирота на порту = белый экран. Порт держит процесс прошлой сессии, pm2 падает с EADDRINUSE, а отвечает старая сборка — её HTML ссылается на чанки, которых после пересборки уже нет. Лечение: pm2 stop → fuser -k -n tcp <порт> → порт пуст → pm2 start. Слушатель — потомок ЛЮБОЙ глубины, идти вверх по ppid.
• Твоя сборка и сборка панели сталкиваются. Их разводит /tmp/fractera-deploy.lock; deploy.sh его соблюдает, ручной npm run build — нет.

6. Граница: что доставка не заменяет

Правишь только /opt/fractera/app. Развёртывание стирает слот тем же rm -rf, что ставит платформу заново — через развёртывание проект переносит только push в репозиторий владельца. Значит доставка файлами хороша, чтобы увидеть работу сейчас, и не хороша как способ «сохранить»: не отправил — потерял при первом же развёртывании.

6a. 🔒 Нет FRACTERA_SSH_* — это НЕ «доступа нет». Это «кнопку ещё не нажали»

✗ Оплачено часом поисков владельца 2026-08-24. Прежний текст здесь говорил «второй канал закрыт, обходить нечего» — и все, включая федерального агента, заключили, что доставки не существует. На самом деле дверь выдачи ключа была построена и стояла на сервере, а кнопки к ней не построил никто.

🔒 Звено ровно одно, и оно проверяется одной строкой: есть ли в .env.local строка FRACTERA_SSH_KEY_B64. Выгрузка окружения сама заводит ключ на сервере, если его ещё нет, и кладёт приватную половину в тот же файл. Файл ключа на диске не нужен: run.sh разворачивает его в .fractera-ssh/ с правами 600 при первом обращении.

Нет строки — значит владелец не скачивал .env.local с тех пор, как панель получила эту сборку. Не «доступа нет», а «файл устарел».

✗ Первая версия этой правки просила скачать ключ ОТДЕЛЬНОЙ кнопкой и положить его руками в папку. Владелец отклонил: четыре ручных действия там, где хватает одного. Не предлагай ему переносить файлы — предлагай нажать одну кнопку.

Что сказать владельцу — одной фразой

Не «нет доступа» и не «впишите переменную». Продиктуй ему это:

Откройте панель → «Переменные окружения» → нажмите кнопку .env.local и сохраните файл в корень проекта. Всё, больше ничего делать не нужно: ключ доступа заводится сам и едет внутри этого файла.

Панель показывает состояние словами прямо под кнопками: «ключ выдан» или «ключ ещё НЕ выдан». Не видно ни кнопки, ни строки состояния — панель на сервере старой сборки, скажи об этом владельцу.

Отзыв. Ключ отзывается той же дверью методом DELETE; прежний перестаёт открывать сервер немедленно. Сам не отзывай — это решение владельца.

🛑 Второй транспорт в обход deploy.sh не изобретать ни при каком из трёх обрывов.

7. Чего не делать

• Не говорить «развёрнуто», не получив оба пруфа.
• Не лечить слот вместо источника: правка живёт до первого развёртывания.
• Не запускать next start руками — так рождаются сироты на порту.
• Не пересказывать таблицу скриптов из инструкции: она там, здесь порядок и доказательства.