modx-docker

modx-docker on GitHub is neither a MODX Extra nor just another transport package. It is a dedicated infrastructure solution for the reproducible launch of MODX projects in Docker.

The main objective of the project is to provide developers with a way to spin up a specific state of MODX and its runtime without having to rebuild their entire local machine for it.

This is especially important for MODX Revolution, where the actual compatibility of a project is often determined not by a single version of the CMS, but by an entire combination of factors:

MODX
+ PHP
+ MySQL / MariaDB
+ Composer
+ specific Extras
+ custom project code
+ database state
+ file system state

An older working project may depend on a very specific combination of these parts. Simply trying to move it to a modern PHP or a new database version often leads to a chain of incompatibilities. modx-docker is created as a tool that allows you to first reproduce the original working environment, and only then safely research, update, or migrate the project.

What the current version does

Currently, the repository sets up a minimal stack:

nginx
  ↓
PHP-FPM
  ↓
MySQL

+ phpMyAdmin

MODX source files are not baked into a pre-built image. Instead, the environment pulls the required version of Revolution directly from Git and performs an automated installation.

This is a deliberate choice: you can run not only a published release, but also the required branch, tag, or potentially a specific commit of the core.

The installation is performed without a browser setup wizard and is broken down into separate stages: directory preparation, fetching source files, creating the database, Composer, building the core transport, CLI setup, and adapting the configuration to the Docker environment.

After startup, the source files remain accessible on the developer's file system, so you can work with them using standard Git tools and your editor, while the application continues to run inside the isolated runtime.

Research version with MiniShop3

A research branch is being developed in parallel to test the next level of the idea: not only automatically installing MODX from Git, but also building from source and natively installing the related stack: pdoTools 3 + VueTools + MiniShop3.

This version is not yet considered a ready, stable workflow — the direction is still being researched. The main hypothesis is that MODX and Extras can be reproducibly built from specific Git refs using standard component build scripts and the MODX Transport API, without manual installation via the Manager.

Details, the current pipeline, and limitations are described separately: modx-docker-minishop.

Why this is needed

Development for a specific version of MODX

One project may require MODX 2.x and old PHP, while another requires MODX 3.x and a modern runtime. Instead of globally switching PHP, MySQL, and system libraries, each project gets its own dedicated environment.

Locally, this allows you to simultaneously run multiple sites with incompatible requirements:

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

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

Project C
└── another legacy configuration

Environments should not interfere with each other and do not require turning the developer's working system into a collection of old, globally installed runtimes.

Researching legacy projects

For MODX, this is one of the primary use cases.

A large number of working websites were created many years ago and depend on specific versions of the core and Extras. When such a project needs to be fixed or upgraded, the first step should not be an immediate attempt to update everything to the latest versions, but rather obtaining a reproducible working state.

modx-docker should allow you to do roughly the following:

spin up the required MODX
→ select the necessary PHP and DB runtime
→ reproduce the project
→ find incompatibilities
→ gradually update the environment

This turns Docker not just into a development convenience, but into a laboratory for maintaining and migrating legacy systems.

Developing and testing MODX itself

Since Revolution is pulled directly from Git, the environment is also suitable for working with the MODX core.

You can check out the required branch or change, reproduce an issue, modify the core code, and check the result in a real application without preparing a separate Docker image for each iteration.

In the future, the same approach can be used to test MODX changes across multiple combinations of PHP and databases.

Why reproducibility matters

The value of such an environment is not that the site was successfully launched once on a specific developer's computer.

It is important to be able to obtain the exact same state again a month or a year from now using declarative configuration and source data.

Therefore, the architectural direction of the project is to gradually extract runtime characteristics into parameters:

MODX_REF
PHP_VERSION
DB_ENGINE
DB_VERSION
COMPOSER_VERSION

The exact set is still evolving, but the general principle is that the environment version should be part of the project description, rather than a hidden property of the developer's computer.

A real MODX project is more than just Git

MODX has an important feature: a significant portion of the project state is traditionally stored in the database.

This may include:

• Resources;
• Templates;
• Chunks;
• Snippets;
• TVs;
• System Settings;
• state of installed packages;
• other configuration entities.

Simultaneously, the file system contains assets, components, custom PHP code, Extras files, and sometimes modifications to the core itself.

Therefore, a clean MODX installation is not enough to reproduce an arbitrary real-world website.

The next important direction for modx-docker is supporting project restoration from source data:

• database dump only;
• files only;
• database and files together;
• or a clean installation without snapshots.

After such a restoration, the environment should be able to adapt the project settings to the local Docker runtime: database connection parameters, domain, paths, cache, and other environment-specific values.

Docker-in-Docker and project isolation

The repository provides an external Docker container inside of which its own Docker daemon can run and the project's internal Compose stack can be launched.

This solution is not meant for simply launching a single site manually, but for a more general scenario of managing isolated project environments.

Instead of giving the management process access to the Docker daemon of the entire machine, you can create a distinct project boundary:

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

This approach allows you to locally manage multiple independent sites—each with its own set of services and versions—without mixing their internal states.

Connection to AI-assisted development

modx-docker is also used as a practical runtime for a broader direction: developing and maintaining web projects using AI agents.

It is not enough for an agent to only see the files in a Git repository. To truly diagnose and modify an older project, it needs the ability to spin up the application, execute code in the correct environment, see errors, verify changes, and repeat the experiment.

In this context, modx-docker acts as a reproducible runtime adapter for MODX:

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

MODX is an especially good testing ground for this approach due to the large number of legacy projects and heavy reliance on specific version combinations.

Current state of the project

The project is under active development. The current version already demonstrates the basic scenario: fetching a specified MODX version from Git, assembling the necessary environment, and automatically installing it in Docker.

Further development focuses on runtime parameterization, working with real project snapshots, and more convenient programmatic environment management.

Current code and updates are available in the open repository: github.com/MODX-Club/modx-docker.