modx-docker

modx-docker на GitHub — это не MODX Extra и не очередной transport package. Это отдельное инфраструктурное решение для воспроизводимого запуска MODX-проектов в Docker.

Главная задача проекта — дать разработчику возможность поднять конкретное состояние MODX и его runtime, не перестраивая под него всю локальную машину.

Это особенно важно для MODX Revolution, где реальная совместимость проекта часто определяется не одной версией CMS, а целой комбинацией:

MODX
+ PHP
+ MySQL / MariaDB
+ Composer
+ конкретные Extras
+ кастомный код проекта
+ состояние базы данных
+ состояние файловой системы

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

Что делает текущая версия

На данный момент репозиторий поднимает минимальный стек:

nginx
  ↓
PHP-FPM
  ↓
MySQL

+ phpMyAdmin

Исходники MODX не зашиваются в готовый image. Вместо этого окружение получает нужную версию Revolution непосредственно из Git и выполняет автоматическую установку.

Это принципиальный выбор: можно запускать не только опубликованный релиз, но и нужную ветку, tag или в перспективе конкретный commit ядра.

Установка выполняется без браузерного setup wizard и разбита на отдельные стадии: подготовка директории, получение исходников, создание базы, Composer, сборка core transport, CLI setup и адаптация конфигурации к Docker-окружению.

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

Исследовательская версия с MiniShop3

Отдельно развивается research-ветка, которая проверяет следующий уровень идеи: не только автоматически устанавливать MODX из Git, но и собирать из исходников и нативно устанавливать связанный стек pdoTools 3 + VueTools + MiniShop3.

Эта версия пока не считается готовым стабильным workflow — направление только исследуется. Основная гипотеза состоит в том, что MODX и Extras можно воспроизводимо собирать из конкретных Git refs, используя штатные build scripts компонентов и MODX Transport API, без ручной установки через Manager.

Подробности, текущий pipeline и ограничения описаны отдельно: modx-docker-minishop.

Зачем это нужно

Разработка под конкретную версию MODX

Один проект может требовать MODX 2.x и старый PHP, другой — MODX 3.x и современный runtime. Вместо глобального переключения PHP, MySQL и системных библиотек каждый проект получает собственную среду.

Локально это позволяет одновременно держать несколько сайтов с несовместимыми требованиями:

Project A
└── MODX 2.x / PHP 7.4 / MySQL 5.7

Project B
└── MODX 3.x / PHP 8.2 / MySQL 8

Project C
└── другая историческая конфигурация

Окружения не должны мешать друг другу и не требуют превращать рабочую систему разработчика в набор старых глобально установленных runtime.

Исследование legacy-проектов

Для MODX это один из основных сценариев.

Большое количество работающих сайтов создавалось много лет назад и зависит от конкретных версий ядра и Extras. Когда такой проект нужно починить или модернизировать, первым шагом должна быть не попытка сразу обновить всё до последних версий, а получение воспроизводимого рабочего состояния.

modx-docker должен позволить сказать примерно следующее:

поднять нужный MODX
→ подобрать нужный PHP и DB runtime
→ воспроизвести проект
→ найти несовместимости
→ постепенно обновлять окружение

Это превращает Docker не просто в удобство разработки, а в лабораторию для сопровождения и миграции legacy-систем.

Разработка и тестирование самого MODX

Так как Revolution берётся непосредственно из Git, окружение подходит и для работы с ядром MODX.

Можно checkout'ить нужную ветку или изменение, воспроизводить issue, менять код ядра и проверять результат в реальном приложении без подготовки отдельного Docker image для каждой итерации.

В дальнейшем тот же подход может использоваться для проверки изменений MODX на нескольких комбинациях PHP и базы данных.

Почему важна воспроизводимость

Ценность такого окружения не в том, что сайт удалось один раз запустить на компьютере конкретного разработчика.

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

Поэтому архитектурное направление проекта — постепенно выносить характеристики runtime в параметры:

MODX_REF
PHP_VERSION
DB_ENGINE
DB_VERSION
COMPOSER_VERSION

Конкретный набор ещё развивается, но общий принцип состоит в том, что версия среды должна быть частью описания проекта, а не скрытым свойством компьютера разработчика.

Реальный MODX-проект — это не только Git

У MODX есть важная особенность: существенная часть проектного состояния традиционно хранится в базе данных.

Там могут находиться:

• Resources;
• Templates;
• Chunks;
• Snippets;
• TVs;
• System Settings;
• состояние установленных пакетов;
• другие конфигурационные сущности.

Одновременно в файловой системе находятся assets, компоненты, кастомный PHP-код, файлы Extras и иногда изменения самого ядра.

Поэтому чистой установки MODX недостаточно для воспроизведения произвольного реального сайта.

Следующее важное направление modx-docker — поддержка восстановления проекта из исходных данных:

• только дамп базы;
• только файлы;
• база и файлы вместе;
• либо чистая установка без snapshot.

После такого восстановления окружение должно уметь адаптировать настройки проекта к локальному Docker runtime: параметры подключения к базе, домен, пути, cache и другие environment-specific значения.

Docker-in-Docker и изоляция проектов

В репозитории предусмотрен внешний Docker-контейнер, внутри которого может работать собственный Docker daemon и запускаться внутренний Compose-стек проекта.

Это решение нужно не для простого ручного запуска одного сайта, а для более общего сценария управления изолированными проектными средами.

Вместо предоставления управляющему процессу доступа к Docker daemon всей машины можно создать отдельную границу проекта:

Project environment
└── own Docker daemon
    ├── nginx
    ├── php-fpm
    ├── database
    └── additional services

Такой подход позволяет локально управлять несколькими независимыми сайтами, у каждого из которых собственный набор сервисов и версий, не смешивая их внутреннее состояние.

Связь с AI-разработкой

modx-docker также используется как практический runtime для более общего направления: разработки и сопровождения веб-проектов с помощью AI-агентов.

Для агента недостаточно видеть только файлы Git-репозитория. Чтобы реально диагностировать и менять старый проект, ему нужно иметь возможность поднять приложение, выполнить код в корректном окружении, увидеть ошибки, проверить изменения и повторить эксперимент.

В этом контексте modx-docker выполняет роль воспроизводимого runtime-адаптера для MODX:

AI / developer
      ↓
project state
      ↓
modx-docker
      ↓
real MODX runtime

MODX является особенно хорошим полигоном для такого подхода из-за большого количества исторических проектов и сильной зависимости от конкретных комбинаций версий.

Текущее состояние проекта

Проект находится в активной разработке. Текущая версия уже демонстрирует базовый сценарий: получить заданную версию MODX из Git, собрать необходимое окружение и автоматически установить её в Docker.

Дальнейшее развитие сосредоточено вокруг параметризации runtime, работы с реальными snapshot проектов и более удобного программного управления окружениями.

Актуальный код и изменения доступны в открытом репозитории: github.com/MODX-Club/modx-docker.