Worklog for task "Add functionality to run MODX websites"
Research on MODX Runtime and Legacy Reproducibility Direction
An analysis of the current repository https://github.com/MODX-Club/modx-docker, project tasks, and MODX Community discussion https://community.modx.com/t/an-open-letter-to-modx-leadership-and-the-modx-revolution-team/9247 has been conducted.
Main Motivation of the Project
It has been confirmed that the key value of modx-docker is not just a local Docker stack for MODX, but the ability to reproducibly spin up specific historical configurations of MODX projects.
For a real legacy MODX project, compatibility is usually determined not only by the core version, but by a combination of:
- MODX Revolution version;
- PHP version;
- MySQL/MariaDB version;
- specific versions of Extras;
- custom components and patches;
- database state;
- project file system state.
Therefore, the project's direction should be viewed as a runtime for researching, supporting, and migrating legacy MODX sites, as well as potentially for testing MODX itself across different historical environments.
What Already Exists in modx-docker
The current implementation sets up an nginx + php-fpm + mysql + phpMyAdmin stack and performs an unattended installation of MODX from GitHub.
The strong point of the current approach is that MODX is taken directly from the git repository, allowing a specific ref/branch/version to be selected, with source code available in a bind mount. This makes it possible to use the environment not only for website development, but also for reproducing bugs, checking specific commits, and developing MODX itself.
The installation is broken down into separate shell stages: directory preparation, clone, database creation, composer install, core transport build, CLI setup, configuration patch. This is a good foundation for further programmable installation.
Architectural Conclusion
modx-docker is better viewed as a specialized runtime adapter rather than an independent project management system.
Project management, directories, git state, dev/stage/prod environments, and agent scenarios should remain at the general platform level. modx-docker should be responsible for the reproducible MODX runtime.
Going forward, the model looks roughly like this:
Agent
-> Project management
-> Git / filesystem
-> Code analysis
-> Knowledge / worklogs
-> Runtime
-> MODX adapter
-> modx-docker
Why Legacy Support is Becoming a Central Feature
The discussion in the MODX Community confirmed that Revolution is effectively moving toward a long-lived legacy/maintenance platform: the priority is stability, security, and compatibility, while significant modernization is expected in a separate future solution.
This means that the large installed base of MODX Revolution will continue to exist for many years as a multitude of historical combinations of core, PHP, DB, and Extras.
Therefore, older PHP/MySQL versions in modx-docker should be treated not as technical debt of the tool itself, but as consciously supported parameters of a laboratory environment.
It is advisable to gradually parameterize at least:
MODX_REF
PHP_VERSION
DB_ENGINE
DB_VERSION
COMPOSER_VERSION
It is also worth using the concept of git ref rather than just branch, so that a tag, branch, or specific MODX commit can be run.
A Real MODX Project Cannot Be Restored Only from Git
An important architectural limit: a significant portion of the MODX state is stored in the database:
- resources;
- templates;
- chunks;
- snippets;
- TVs;
- system settings;
- package state;
- other configuration entities.
At the same time, a substantial part of the project resides in the file system:
- assets;
- components;
- custom code;
- Extras files;
- sometimes the core itself and local modifications within it.
Therefore, for a full reproduction of a real project, it is necessary to be able to restore the database and file system independently or together.
Solution: Snapshot/Restore Support
Based on the discussion, a separate task has been created: /tasks/cmtngfoe204qdpf0qab6spl66 — "Add MODX project restoration from dumps and files".
It defines four basic scenarios:
- clean MODX installation;
- database-only restoration;
- files-only restoration;
- full snapshot: files + DB.
For the snapshot mode, it is important not to modify the original archives/dumps, but to work with a copy of them and then normalize environment-specific data inside the working environment.
After restoration, automatic normalization may be required for:
- DB connection parameters;
- domain/hostname;
- absolute paths;
- cache/session paths;
- context URLs/connectors;
- other settings tied to the old server.
Potential Agent Workflow
The target model could look like this:
User provides old MODX site
-> agent determines MODX version and dependencies
-> selects PHP/DB runtime
-> restores files and DB
-> normalizes environment
-> launches site
-> analyzes errors and incompatibilities
-> gradually updates runtime/code
-> records results in worklogs/knowledge
This turns modx-docker into a laboratory not only for launching, but also for migrating legacy projects.
For example, an agent could potentially sequentially check compatibility with PHP/MySQL versions, find the point of failure, fix the code, and continue moving toward a more modern runtime.
Additional Perspective: Testing MODX Revolution
The same infrastructure is potentially suitable for testing MODX core PRs across different environments and real project snapshots.
Instead of checking only a single modern set, changes can be run through a matrix of historical configurations to detect regressions. This is especially relevant for Revolution, where backward compatibility is one of the main values and simultaneously a source of high manual verification costs.
Summary
The refined purpose of modx-docker:
A reproducible MODX runtime for an agent-based project management system, primarily designed for launching, researching, supporting, and migrating legacy configurations with specific versions of MODX, PHP, database, Extras, and project state.
The nearest architectural priority is not to overload modx-docker with its own project management system, but to make it a well-parameterized runtime primitive with predictable stages of build -> install/restore -> normalize -> ready/failed and support for real snapshots.