Ворклог по задаче "Добавить функционал для запуска MODX-сайтов"

Исследование направления MODX runtime и legacy-воспроизводимости

Проведён разбор текущего репозитория https://github.com/MODX-Club/modx-docker, задач проекта и обсуждения MODX Community: https://community.modx.com/t/an-open-letter-to-modx-leadership-and-the-modx-revolution-team/9247.

Главный мотив проекта

Подтвердилось, что ключевая ценность modx-docker — не просто локальный Docker-стек для MODX, а возможность воспроизводимо поднимать конкретные исторические конфигурации MODX-проектов.

Для реального legacy MODX-проекта совместимость обычно определяется не только версией ядра, а комбинацией:

• версия MODX Revolution;
• версия PHP;
• версия MySQL/MariaDB;
• конкретные версии Extras;
• кастомные компоненты и патчи;
• состояние базы данных;
• состояние файловой системы проекта.

Поэтому направление проекта следует рассматривать как runtime для исследования, поддержки и миграции legacy MODX-сайтов, а также потенциально для тестирования самого MODX на разных исторических окружениях.

Что уже есть в modx-docker

Текущая реализация поднимает стек nginx + php-fpm + mysql + phpMyAdmin и выполняет unattended-установку MODX из GitHub.

Сильная сторона текущего подхода — MODX берётся именно из git-репозитория и можно выбрать конкретный ref/ветку/версию, а исходники доступны в bind mount. Это позволяет использовать окружение не только для разработки сайтов, но и для воспроизведения багов, проверки конкретных коммитов и разработки самого MODX.

Установка разбита на отдельные shell-стадии: подготовка директории, clone, создание БД, composer install, сборка core transport, CLI setup, patch конфигурации. Это хорошая основа для дальнейшей программируемой установки.

Архитектурный вывод

modx-docker лучше рассматривать как специализированный runtime adapter, а не как самостоятельную систему управления проектами.

Управление проектами, директориями, git-состоянием, окружениями dev/stage/prod и агентными сценариями должно оставаться на уровне общей платформы. modx-docker должен отвечать за воспроизводимый MODX runtime.

В перспективе модель выглядит примерно так:

Agent
  -> Project management
  -> Git / filesystem
  -> Code analysis
  -> Knowledge / worklogs
  -> Runtime
       -> MODX adapter
            -> modx-docker

Почему legacy-поддержка становится центральной функцией

Обсуждение на MODX Community подтвердило, что Revolution фактически движется в сторону long-lived legacy/maintenance-платформы: приоритет — стабильность, безопасность и совместимость, а существенная модернизация предполагается уже в отдельном будущем решении.

Это означает, что большая установленная база MODX Revolution ещё много лет будет существовать в виде множества исторических комбинаций ядра, PHP, БД и Extras.

Поэтому старые версии PHP/MySQL в modx-docker следует воспринимать не как технический долг самого инструмента, а как осознанно поддерживаемые параметры лабораторного окружения.

Желательно постепенно параметризовать как минимум:

MODX_REF
PHP_VERSION
DB_ENGINE
DB_VERSION
COMPOSER_VERSION

Также стоит использовать понятие git ref, а не только branch, чтобы можно было запускать tag, branch или конкретный commit MODX.

Реальный MODX-проект нельзя восстановить только из Git

Важный архитектурный предел: значительная часть MODX-состояния хранится в базе данных:

• resources;
• templates;
• chunks;
• snippets;
• TVs;
• system settings;
• package state;
• другие конфигурационные сущности.

При этом существенная часть проекта находится в файловой системе:

• assets;
• components;
• кастомный код;
• файлы Extras;
• иногда само ядро и локальные изменения в нём.

Поэтому для полноценного воспроизведения реального проекта необходимо уметь восстанавливать БД и файловую систему независимо или совместно.

Решение: поддержка snapshot/restore

По результатам обсуждения вынесена отдельная задача: /tasks/cmtngfoe204qdpf0qab6spl66 — «Добавить восстановление MODX-проекта из дампов и файлов».

В ней зафиксированы четыре базовых сценария:

1. чистая установка MODX;
2. восстановление только БД;
3. восстановление только файлов;
4. полный snapshot: файлы + БД.

Для snapshot-режима важно не изменять исходные архивы/дампы, а работать с их копией и затем нормализовать environment-specific данные уже внутри рабочего окружения.

После восстановления может понадобиться автоматическая нормализация:

• параметров подключения к БД;
• домена/hostname;
• абсолютных путей;
• cache/session paths;
• context URLs/connectors;
• других настроек, привязанных к старому серверу.

Потенциальный агентный workflow

Целевая модель может выглядеть так:

Пользователь предоставляет старый MODX-сайт
        -> агент определяет версию MODX и зависимости
        -> подбирает PHP/DB runtime
        -> восстанавливает файлы и БД
        -> нормализует окружение
        -> запускает сайт
        -> анализирует ошибки и несовместимости
        -> постепенно обновляет runtime/код
        -> фиксирует результаты в worklogs/knowledge

Это превращает modx-docker в лабораторию не только запуска, но и миграции legacy-проектов.

Например, агент потенциально может последовательно проверять совместимость с версиями PHP/MySQL, находить точку отказа, исправлять код и продолжать движение к более современному runtime.

Дополнительная перспектива: тестирование MODX Revolution

Та же инфраструктура потенциально подходит для тестирования PR ядра MODX на разных окружениях и реальных project snapshots.

Вместо проверки только одного современного набора можно прогонять изменения по матрице исторических конфигураций и выявлять regressions. Это особенно релевантно для Revolution, где backward compatibility является одной из главных ценностей и одновременно источником высокой стоимости ручной проверки.

Итог

Уточнённое назначение modx-docker:

Воспроизводимый MODX runtime для агентной системы управления проектами, рассчитанный прежде всего на запуск, исследование, поддержку и миграцию legacy-конфигураций с конкретными версиями MODX, PHP, базы данных, Extras и проектного состояния.

Ближайший архитектурный приоритет — не усложнять modx-docker собственной системой управления проектами, а сделать его хорошо параметризуемым runtime primitive с предсказуемыми стадиями build -> install/restore -> normalize -> ready/failed и поддержкой реальных snapshots.