Project Description

Contents
  1. Requirements
  2. Structure
  3. Installation on hosting
  4. Update
  5. Images and video
  6. Design themes
  7. Machine translation: Gemini or Claude
  8. Useful commands
  9. Development
  10. Release

Kometa

A personal CMS with static generation: content is stored in MySQL, and the site is served as ready-made HTML files directly by the web server. PHP runs only in the admin panel (a separate subdomain), on 404 / redirect pages, and during lazy generation of missing pages.

The full technical specification is in the project «CMS» on claude.ai.

Status: 0.4 — stage 2 and media improvements: folders, filters and search in the media library, MP4/WebM video, images in text in various sizes with text wrapping, galleries and click-to-view, file addresses without dates, page copying, the «Blog» section in the admin panel. Next — stage 3: Cloudflare, IndexNow, scheduled publishing, analytics, SEO audit, backups.

Requirements

  • PHP 8.4+ (8.5 recommended): pdo_mysql, mbstring, dom, curl, fileinfo, zip, gd with JPEG support (WebP and AVIF are also desirable); preferably intl, OPcache

  • MySQL 8 / MariaDB 10.6+

  • Apache 2.4 with mod_rewrite or nginx

  • Two addresses: the site (example.com) and the admin panel subdomain (admin.example.com)

Structure

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/          сборка архива релиза

Only public_html and admin_html face outward; all the other code sits one level higher.

Installation on hosting

  1. Download kometa-X.Y.Z.zip from releases and unpack it into the account's home folder so that public_html and admin_html end up next to app/.

  2. In the hosting panel:

    • document root of the main domain → …/public_html;

    • create the admin panel subdomain, document root → …/admin_html;

    • create a MySQL database and user.

  3. Open the admin panel address. The installer will check the server and ask for the installation token — it is in the file storage/install-token (open it via FTP or file manager). This way no outsider can install the site before you do.

  4. After installation, log in and set up a second factor (Google Authenticator, Aegis, 2FAS, etc.). Save the backup codes.

For nginx, see docs/nginx.conf.

Update

On a server with SSH:

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

Without SSH — in the admin panel: the version number link in the header → «Update» (page /system/update, rollback is there too). Or upload the archive manually and run php bin/kometa update --file=kometa-X.Y.Z.zip.

The update replaces only the code (app/, vendor/, bin/, migrations/, admin_html/, public_html/index.php, etc.). Configuration, storage/ and generated pages are not touched. The previous version is kept in storage/releases/ (last 3). Database migrations only go forward: rollback restores the code but not the schema.

For a private repository, specify in config/config.php → update.token a fine-grained GitHub token with the Contents: Read-only permission.

After the update, the site is automatically rebuilt using the new templates (pages whose HTML has not changed are not overwritten).

Images and video

  • Files are stored at addresses like /media/fa/foto-fa4046-960.webp: fa — the beginning of the content hash; the upload date is not visible in the address. Old addresses with dates (before 0.4) respond with 301 redirects to the new ones.

  • The site serves downscaled copies at the widths from theme.json → image_sizes (by default 480, 960, 1440, 1920) in AVIF / WebP / JPEG; the browser itself picks the right one based on srcset and sizes. The original is stored at no more than 2560 px on the long side.

  • Image size in text — in the panel above the image in the editor: full text width, large (540 px), medium (360 px), small (240 px); wrapping left / right / center; «Zoom on click» opens the viewer. Several images side by side — the «Gallery» block.

  • MP4 / WebM video is uploaded to the media library as is (without re-encoding); the size is limited by the hosting's PHP settings (upload_max_filesize, post_max_size). The cover can be any image from the media library.

Design themes

The theme is enabled in the admin panel: «Themes» → preview → «Enable» (the site will rebuild itself).

Folder

Theme

Character

Fonts

default

Kometa — standard

neutral, narrow column

system

paper

Paper

warm, with serifs

system

meridian

Meridian

business and reference, blue accent

Golos Text

journal

Journal

for articles and blog, centered header, drop cap

Literata + high-contrast serif for headings

graphite

Graphite

technical, always dark

JetBrains Mono + Onest

aurora

Aurora

soft, text on a white sheet

Manrope

signal

Signal

Swiss typography: strict grid, large grotesque, one signal color

Inter Tight + JetBrains Mono

bloknot

Notepad

personal site: left column with the author, menu and calendar

Spectral + JetBrains Mono

All themes except «Graphite» follow the system's light or dark scheme. Fonts are bundled within the theme itself (assets/fonts/*.woff2, OFL license), so they look the same for all visitors and do not depend on third-party servers; each file includes Latin and Cyrillic (Russian, Ukrainian, Belarusian).

Custom theme with a font: in CSS, paths are written as in a regular file from assets/css/ — src: url("../fonts/x.woff2"); the engine will insert the address into public_html/assets/<тема>/ with a content hash. Body text fonts should be listed in theme.json → "preload_fonts": ["fonts/x.woff2"], so they start loading earlier.

Machine translation: Gemini or Claude

In config/config.php add the key of the required service:

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

The service, model and glossary of terms are in the admin panel, «Settings → Machine translation»; the same place has the «Check key and test translation» button. You can translate one page (button in the editor) or several (checkboxes in the page list). Translations are saved with the status «machine»: new ones as drafts.

How a page is translated:

  1. First the fields — title, excerpt, SEO title and description, tags.

  2. Then the text in fragments split along block boundaries (paragraphs, lists, tables). With each request the model receives context: the page title and excerpt with their translation, and the end of the previous fragment with its translation — this keeps terms, forms of address and style consistent.

  3. Fragment size is chosen automatically: Kometa extends max_execution_time if the hosting allows it, reads the actual limit and measures the service speed on each fragment. With a 30 s limit fragments are about 1500 characters, with 120 s — 5–8 thousand (a regular article takes one or two requests). If the hosting allows it, raise max_execution_time to 120 s.

  4. A fragment that the service failed to answer twice is split in half.

  5. If the model is overloaded (Gemini 503 «high demand» — new Flash models can have this for hours), the request goes immediately to the fallback models from the settings (by default gemini-flash-lite-latest, gemini-2.5-flash, gemini-2.5-flash-lite). If all of them are busy, the pause grows: 10, 20, 40 s… up to 5 minutes.

Without a time limit and with maximum fragments, translation is run by the console:

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

Useful commands

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                                  # пересобрать весь сайт

Development

docker compose up -d
docker compose exec php composer install

The site — http://localhost:8080, admin panel — http://localhost:8081. In the installer: database server db, database/user/password kometa.

The editor (TipTap + CodeMirror) is built into admin_html/assets/editor/; the built files are stored in the repository, and Node.js is needed only for changing the editor:

cd editor && npm ci && npm run build

Checks (also run by 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

Release

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

GitHub Actions will build kometa-0.2.0.zip with dependencies and a checksum and publish the release.