Project Description
Contents
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,gdwith JPEG support (WebP and AVIF are also desirable); preferablyintl, 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
-
Download
kometa-X.Y.Z.zipfrom releases and unpack it into the account's home folder so thatpublic_htmlandadmin_htmlend up next toapp/. -
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.
-
-
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. -
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 onsrcsetandsizes. 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 |
|---|---|---|---|
|
Kometa — standard |
neutral, narrow column |
system |
|
Paper |
warm, with serifs |
system |
|
Meridian |
business and reference, blue accent |
Golos Text |
|
Journal |
for articles and blog, centered header, drop cap |
Literata + high-contrast serif for headings |
|
Graphite |
technical, always dark |
JetBrains Mono + Onest |
|
Aurora |
soft, text on a white sheet |
Manrope |
|
Signal |
Swiss typography: strict grid, large grotesque, one signal color |
Inter Tight + JetBrains Mono |
|
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:
-
First the fields — title, excerpt, SEO title and description, tags.
-
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.
-
Fragment size is chosen automatically: Kometa extends
max_execution_timeif 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, raisemax_execution_timeto 120 s. -
A fragment that the service failed to answer twice is split in half.
-
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.