Що робити, якщо…

Усі команди — на сервері, під користувачем deploy, з каталогу /opt/tabula/app:

ssh deploy@<IP>
cd /opt/tabula/app

Для стислості нижче dc означає docker compose -f docker-compose.prod.yml. Можна задати таке скорочення на час сеансу:

alias dc='docker compose -f docker-compose.prod.yml'

Після будь-якої зміни .env застосунок треба перестворити, щоб він прочитав нові значення:

dc up -d --force-recreate app

1. Сайт не відкривається

Що запущено:
Terminal window
```
dc ps
```
Мають бути app, nginx, certbot, у app — healthy. Якщо чогось немає — dc up -d.
Що пише застосунок:
Terminal window
```
dc logs --tail=100 app
```
Найчастіші причини в журналі:
- «Відсутні обов’язкові змінні оточення: SESSION_SECRET» — заповніть SESSION_SECRET у .env;
- «SESSION_SECRET закороткий…» — потрібно щонайменше 32 символи: openssl rand -hex 32 (нове значення виведе всіх з адмін-панелі);
- «Не налаштовано пошту для форми зворотного звʼязку…» — заповніть EMAIL_USER/EMAIL_PASS або SMTP_*;
- «Некоректний SITE_URL…», «Некоректний SITE_SLUG…», «Некоректний UPDATE_REPO…», «Некоректний PORT…», «Некоректний LOG_LEVEL…» — виправте значення за підказкою в повідомленні;
- помилки доступу до /data (permission denied, EACCES) — віддайте каталоги даних користувачу сайту (так буває після оновлення зі старішої версії або перенесення каталогів вручну):
  Terminal window
```
dc run --rm --no-deps --user root app chown -R app:app /data /backups
dc up -d app
```
Якщо dc відповідає, що не задано APP_IMAGE або SITE_DOMAIN, — ці змінні відсутні в .env.
Якщо все запущено, а сайт не відкривається лише за доменом — перевірте DNS (nslookup school.example.ua з вашого комп’ютера має показати IP сервера) і чи не закінчилася оплата домену або сервера.
Переконайтеся, що диск не заповнений (п. 3).

2. Браузер пише, що сертифікат недійсний або прострочений

Сертифікат Let’s Encrypt діє 90 днів; контейнер certbot продовжує його сам, коли лишається менше 30 днів, а nginx раз на 6 годин перечитує конфігурацію й підхоплює продовжений сертифікат (скрипт nginx/docker-entrypoint.d/90-reload-loop.sh). Тож після продовження новий сертифікат з’являється на сайті щонайпізніше за 6 годин, без жодних дій. Щоб не чекати — перезапустіть nginx:

dc restart nginx

Якщо не допомогло, подивіться, чи продовження взагалі вдається:

dc logs --tail=50 certbot

Причини, через які продовження не вдається: закритий порт 80 (його має бути відкрито — перевірка Let’s Encrypt іде по HTTP), домен більше не вказує на цей сервер. Спробувати продовжити вручну:

dc run --rm --entrypoint certbot certbot renew --webroot -w /var/www/certbot
dc restart nginx

3. Закінчується місце на диску

Скільки вільно:

df -h
curl -s -H "Authorization: Bearer <HEALTH_TOKEN з .env>" https://school.example.ua/health

(у повній відповіді /health — поле disk.freeBytes; без токена /health показує лише status і version). Що займає місце і як звільнити:

старі образи Docker після оновлень: docker image prune -af --filter "until=168h" (невикористані й старші за тиждень); подивитися, скільки займає Docker загалом, — docker system df;
копії, які залишило відновлення: теки /opt/tabula/backups/data.bak-…. Коли ви переконались, що відновлення вдалося, старі можна видалити;
архіви бекапу: зменшіть «Скільки архівів зберігати» в адмін-панелі («Налаштування» → «Бекапи»); зайві видаляться при наступному новому архіві;
невикористані файли: адмін-панель → «Медіа» → «Очистити невикористані» (вони на 30 днів ідуть у кошик, потім видаляються).

Якщо місця постійно бракує — збільште диск у панелі хостингу.

4. Адміністратор забув пароль

Якщо на сайті є інший адміністратор — він встановлює новий пароль в адмін-панелі («Користувачі» → «Редагувати» → «Скинути пароль»).

Якщо адміністратор єдиний, створіть на сервері новий обліковий запис адміністратора (з іншою поштою — скрипт не змінює пароль наявного запису й відповідає «Користувач із email … вже існує.»):

dc exec -i app node scripts/create-user.js --email reserve@school.example.ua --role admin --name "Ім'я Прізвище"

Скрипт двічі попросить пароль (мінімум 10 символів; на екрані він не відображається). Увійдіть з новим записом, у «Користувачі» встановіть новий пароль для старого запису, а тимчасовий деактивуйте (зніміть «Активний»).

5. Загубився код першого налаштування

Код потрібен, лише поки на сайті немає жодного облікового запису.

Якщо код задано в .env (SETUP_CODE) — він там.
Якщо сайт згенерував його сам — він у журналі:
Terminal window
```
dc logs app | grep admin/setup
```
Або задайте новий: впишіть SETUP_CODE=<свій код> у .env і перестворіть застосунок (dc up -d --force-recreate app). Код з .env має перевагу над згенерованим.

Якщо /admin/setup відповідає «не знайдено», сайт уже налаштовано — входьте на /admin. Доступ без пароля повертають, як у п. 4.

6. Форма зворотного зв’язку не надсилає листи

Відвідувач бачить, що лист не вдалося надіслати. Подивіться причину в журналі:

dc logs app | grep -A5 "Помилка відправки листа"

Gmail: в EMAIL_PASS має бути пароль застосунку (App Password), а не звичайний пароль від пошти.
SMTP: перевірте SMTP_HOST, логін і пароль; для порту 465 потрібно SMTP_SECURE=1, для 587 — SMTP_SECURE=0.
Лист надіслано, але не дійшов — перевірте папку «Спам» у скриньці з CONTACT_TO (або в скриньці відправника, якщо CONTACT_TO порожній).

Після зміни .env — dc up -d --force-recreate app і ще один тестовий лист.

7. Бекап не вдався

Текст помилки — в адмін-панелі на сторінці «Бекапи» (блок «Розклад», рядок «помилка») і на дашборді.

«Бекап уже виконується…» — зачекайте кілька хвилин.
Помилка запису в /backups (permission denied) — віддайте каталоги даних користувачу сайту: dc run --rm --no-deps --user root app chown -R app:app /data /backups, потім «Зробити бекап».
Закінчилось місце — п. 3.
Помилка лише в блоці «Копія поза сервером» (локальний архів створено) — перевірте BACKUP_S3_*: адресу сховища, регіон, назву бакета, ключ і чи має ключ право писати й видаляти в цьому бакеті. Після виправлення .env перестворіть застосунок і натисніть «Зробити бекап».

Після виправлення натисніть «Зробити бекап» і переконайтеся, що з’явилося «створено» або «без змін».

8. Після оновлення щось зламалось

Поверніть попередню версію — див. Оновлення → повернутися назад. Якщо й це не допомогло — відновіть бекап, зроблений перед оновленням (Бекапи і відновлення).

9. Змінився домен

Додайте DNS-запис A для нового домену на IP сервера (і www, якщо треба) і дочекайтеся, поки він запрацює.
У .env змініть SITE_DOMAIN і SITE_URL. SITE_SLUG не змінюйте.
Отримайте сертифікат для нового домену і перезапустіть усе:
Terminal window
```
CERTBOT_EMAIL="admin@new-school.example.ua" bash scripts/init-letsencrypt.sh
dc up -d --force-recreate
```
Поки працює скрипт, сайт кілька хвилин відповідає заглушкою.
Перевірте https://<новий-домен>/health.

Старий домен автоматично на новий не переадресовується. Якщо в текстах сторінок є посилання з повною старою адресою — виправте їх в адмін-панелі.

10. Переїзд на інший сервер

На старому сайті попросіть не редагувати його під час переїзду. В адмін-панелі → «Бекапи» → «Зробити бекап».
На новому сервері пройдіть кроки 1–4 встановлення з таким самим .env (особливо той самий SITE_SLUG), але сайт не запускайте.
Відновіть дані до першого запуску:
- якщо налаштовано копію поза сервером — як у розділі Відновлення з копії в сховищі, з найновішим архівом;
- якщо ні — завантажте архів в адмін-панелі старого сайту («Бекапи» → «Завантажити»), скопіюйте його на новий сервер у домашню теку deploy і відновіть звідти:
  Terminal window
```
# на вашому комп'ютері, з теки, де лежить архів:
scp <архів>.tar.gz deploy@<новий-IP>:~/
# далі — на новому сервері:
ssh deploy@<новий-IP>
cd /opt/tabula/app
docker compose -f docker-compose.prod.yml run --rm \
  -e DATA_DIR=/data \
  -v /opt/tabula/data:/data \
  -v /opt/tabula/backups:/backups \
  -v ~/<архів>.tar.gz:/restore/<архів>.tar.gz:ro \
  app node scripts/restore.js /restore/<архів>.tar.gz
```
Змініть DNS-запис A домену на IP нового сервера і дочекайтеся, поки він запрацює.
Пройдіть крок 5 встановлення (запуск і сертифікат). Майстер першого налаштування не потрібен: облікові записи вже є.
Перевірте сайт і адмін-панель, дочекайтеся першого бекапу на новому сервері й лише тоді вимикайте старий.