Опис проєкту

Зміст
  1. Вимоги
  2. Структура
  3. Встановлення на хостинг
  4. Оновлення
  5. Картинки та відео
  6. Теми оформлення
  7. Машинний переклад: Gemini або Claude
  8. Корисні команди
  9. Розробка
  10. Реліз

Комета

Особиста CMS зі статичною генерацією: вміст зберігається в MySQL, а сайт віддається готовими HTML-файлами безпосередньо веб-сервером. PHP працює лише в адмінці (окремий піддомен), на 404 / редиректах і під час лінивої генерації відсутніх сторінок.

Повне технічне завдання — у проєкті «CMS» на claude.ai.

Статус: 0.4 — етап 2 та доопрацювання медіа: папки, фільтри й пошук у медіатеці, відео MP4/WebM, картинки в тексті різного розміру з обтіканням, галереї та перегляд за кліком, адреси файлів без дати, копіювання сторінок, розділ «Блог» в адмінці. Далі — етап 3: Cloudflare, IndexNow, відкладена публікація, аналітика, SEO-аудит, бекапи.

Вимоги

  • PHP 8.4+ (рекомендовано 8.5): pdo_mysql, mbstring, dom, curl, fileinfo, zip, gd з підтримкою JPEG (бажано ще WebP і AVIF); бажано intl, OPcache

  • MySQL 8 / MariaDB 10.6+

  • Apache 2.4 з mod_rewrite або nginx

  • Дві адреси: сайт (example.com) і піддомен адмінки (admin.example.com)

Структура

app/            код CMS (src/ — классы, views/ — шаблоны админки)
admin_html/     document root поддомена админки
public_html/    document root сайта: index.php + .htaccess, остальное генерирует CMS
bin/kometa      командная строка
migrations/     миграции базы
config/         config.php (создаёт установщик, в git не попадает)
storage/        кеш, журналы, сессии, медиа, прошлые версии (в git не попадает)
docs/           пример конфигурации nginx
docker/         локальная среда разработки
build/          сборка архива релиза

Назовні дивляться лише public_html і admin_html; весь інший код лежить рівнем вище.

Встановлення на хостинг

  1. Завантажте kometa-X.Y.Z.zip з релізів і розпакуйте в домашню папку акаунта так, щоб public_html і admin_html опинилися поруч із app/.

  2. У панелі хостингу:

    • document root основного домену → …/public_html;

    • створіть піддомен адмінки, document root → …/admin_html;

    • створіть базу MySQL і користувача.

  3. Відкрийте адресу адмінки. Інсталятор перевірить сервер і попросить токен встановлення — він лежить у файлі storage/install-token (відкрийте через FTP або файловий менеджер). Так ніхто сторонній не встигне встановити сайт раніше за вас.

  4. Після встановлення увійдіть і підключіть другий фактор (Google Authenticator, Aegis, 2FAS тощо). Збережіть резервні коди.

Для nginx дивіться docs/nginx.conf.

Оновлення

На сервері з SSH:

php bin/kometa update            # до последнего релиза
php bin/kometa update v0.2.0     # до конкретной версии
php bin/kometa rollback          # вернуть предыдущую
php bin/kometa releases          # сохранённые версии

Без SSH — в адмінці: посилання з номером версії в шапці → «Оновити» (сторінка /system/update, там же відкат). Або завантажте архів вручну і виконайте php bin/kometa update --file=kometa-X.Y.Z.zip.

Оновлення замінює лише код (app/, vendor/, bin/, migrations/, admin_html/, public_html/index.php тощо). Конфігурація, storage/ і згенеровані сторінки не чіпаються. Попередня версія зберігається в storage/releases/ (останні 3). Міграції бази лише «вперед»: відкат повертає код, але не схему.

Для приватного репозиторію вкажіть в config/config.php → update.token fine-grained токен GitHub з правом Contents: Read-only.

Після оновлення сайт автоматично перебудовується за новими шаблонами (сторінки, у яких HTML не змінився, не перезаписуються).

Картинки та відео

  • Файли зберігаються за адресами виду /media/fa/foto-fa4046-960.webp: fa — початок хешу вмісту, дата завантаження за адресою не видна. Старі адреси з датою (до 0.4) відповідають 301 на нові.

  • На сайт ідуть зменшені копії ширин з theme.json → image_sizes (за замовчуванням 480, 960, 1440, 1920) у AVIF / WebP / JPEG; браузер сам обирає потрібну за srcset і sizes. Оригінал зберігається не більше 2560 px по довшій стороні.

  • Розмір картинки в тексті — у панелі над картинкою в редакторі: на всю ширину тексту, велика (540 px), середня (360 px), мала (240 px); обтікання зліва / справа / по центру; «Збільшувати за кліком» відкриває переглядач. Кілька картинок поруч — блок «Галерея».

  • Відео MP4 / WebM завантажується в медіатеку як є (без перекодування), розмір обмежено налаштуваннями PHP хостингу (upload_max_filesize, post_max_size). Обкладинка — будь-яка картинка з медіатеки.

Теми оформлення

Тема вмикається в адмінці: «Теми» → попередній перегляд → «Увімкнути» (сайт перебудується сам).

Папка

Тема

Характер

Шрифти

default

Комета — стандартна

нейтральна, вузька колонка

системні

paper

Папір

тепла, із засічками

системні

meridian

Меридіан

ділова і довідкова, синій акцент

Golos Text

journal

Журнал

для статей і блогу, шапка по центру, буквиця

Literata + контрастна антиква для заголовків

graphite

Графіт

технічна, завжди темна

JetBrains Mono + Onest

aurora

Аврора

м'яка, текст на білому аркуші

Manrope

signal

Сигнал

швейцарська типографіка: сувора сітка, великий гротеск, один сигнальний колір

Inter Tight + JetBrains Mono

bloknot

Блокнот

особистий сайт: колонка зліва з автором, меню й календар

Spectral + JetBrains Mono

Усі теми, крім «Графіту», слідують світлій або темній схемі системи. Шрифти лежать у самій темі (assets/fonts/*.woff2, ліцензія OFL), тому однаково виглядають у всіх відвідувачів і не залежать від чужих серверів; у кожному файлі є латиниця і кирилиця (російська, українська, білоруська).

Власна тема зі шрифтом: у CSS шляхи пишуться як у звичайному файлі з assets/css/ — src: url("../fonts/x.woff2"), рушій сам підставить адресу в public_html/assets/<тема>/ з хешем вмісту. Шрифти основного тексту варто перелічити в theme.json → "preload_fonts": ["fonts/x.woff2"], тоді вони почнуть завантажуватися раніше.

Машинний переклад: Gemini або Claude

В config/config.php додайте ключ потрібного сервісу:

'gemini' => ['key' => 'AIza…'],      // бесплатно: aistudio.google.com → Get API key
'claude' => ['key' => 'sk-ant-…'],   // platform.claude.com → API Keys, оплата по факту

Сервіс, модель і словник термінів — в адмінці, «Налаштування → Машинний переклад»; там же кнопка «Перевірити ключ і пробний переклад». Перекласти можна одну сторінку (кнопка в редакторі) або кілька (галочки у списку сторінок). Переклади зберігаються зі статусом «машинний»: нові — чернеткою.

Як перекладається сторінка:

  1. Спочатку поля — заголовок, анонс, SEO-заголовок і опис, мітки.

  2. Потім текст фрагментами за межами блоків (абзаци, списки, таблиці). У кожен запит модель отримує контекст: заголовок і анонс сторінки з їх перекладом та кінець попереднього фрагмента з перекладом — так зберігаються терміни, звернення і стиль.

  3. Розмір фрагмента підбирається сам: Комета продовжує max_execution_time, якщо хостинг дозволяє, читає фактичний ліміт і вимірює швидкість сервісу на кожному фрагменті. При ліміті 30 с фрагменти близько 1500 символів, при 120 с — 5–8 тисяч (звичайна стаття іде одним-двома запитами). Якщо хостинг дозволяє, підніміть max_execution_time до 120 с.

  4. Фрагмент, на який сервіс не встиг відповісти двічі, ділиться навпіл.

  5. Якщо модель перевантажена (Gemini 503 «high demand» — у нових Flash це буває годинами), запит одразу йде до запасних моделей з налаштувань (за замовчуванням gemini-flash-lite-latest, gemini-2.5-flash, gemini-2.5-flash-lite). Якщо зайняті всі — пауза зростає: 10, 20, 40 с… до 5 хвилин.

Без обмеження за часом і з максимальними фрагментами переводить консоль:

php bin/kometa translate --missing --langs=en,uk     # всё непереведённое и устаревшее
php bin/kometa translate --pages=12,15 --langs=en    # выбранные страницы
php bin/kometa translate --job=7                     # продолжить задачу, начатую в админке

Корисні команди

php bin/kometa check                                  # проверить сервер, базу, миграции
php bin/kometa migrate                                # применить миграции
php bin/kometa user:create --email=… --name=…         # ещё один администратор
php bin/kometa user:password [email protected]          # сменить пароль
php bin/kometa user:reset-2fa [email protected]         # потеряли телефон и коды
php bin/kometa cache:clear                            # очистить кеш шаблонов
php bin/kometa build                                  # пересобрать весь сайт

Розробка

docker compose up -d
docker compose exec php composer install

Сайт — http://localhost:8080, адмінка — http://localhost:8081. В інсталяторі: сервер бази db, база/користувач/пароль kometa.

Редактор (TipTap + CodeMirror) збирається в admin_html/assets/editor/; зібрані файли лежать у репозиторії, Node.js потрібен лише для зміни редактора:

cd editor && npm ci && npm run build

Перевірки (їх також запускає GitHub Actions):

composer lint
composer stan
KOMETA_TEST_DB_HOST=127.0.0.1 KOMETA_TEST_DB_PORT=3307 KOMETA_TEST_DB_NAME=kometa \
KOMETA_TEST_DB_USER=root KOMETA_TEST_DB_PASS=root composer test

Реліз

echo "0.2.0" > VERSION
git commit -am "Версия 0.2.0"
git tag v0.2.0
git push && git push --tags

GitHub Actions збере kometa-0.2.0.zip із залежностями та контрольною сумою і опублікує реліз.