{"id":51292998,"url":"https://github.com/prihod/docker-modx","last_synced_at":"2026-06-30T12:02:09.666Z","repository":{"id":365583202,"uuid":"910924476","full_name":"Prihod/docker-modx","owner":"Prihod","description":"🐳 Docker-based local development environment for MODX CMS with PHP, MariaDB, Nginx, and advanced developer tools. Features automatic installation, data import/export, Xdebug, phpMyAdmin, MailHog, and more.","archived":false,"fork":false,"pushed_at":"2026-06-18T00:31:53.000Z","size":11844,"stargazers_count":15,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-18T02:20:26.293Z","etag":null,"topics":["blackfire","development-environment","docker","docker-compose","local-development","modx","modx-revolution","xdebug","xhprof"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Prihod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-01T19:59:16.000Z","updated_at":"2026-06-18T00:31:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Prihod/docker-modx","commit_stats":null,"previous_names":["prihod/docker-modx"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Prihod/docker-modx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prihod%2Fdocker-modx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prihod%2Fdocker-modx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prihod%2Fdocker-modx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prihod%2Fdocker-modx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Prihod","download_url":"https://codeload.github.com/Prihod/docker-modx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prihod%2Fdocker-modx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34965643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blackfire","development-environment","docker","docker-compose","local-development","modx","modx-revolution","xdebug","xhprof"],"created_at":"2026-06-30T12:02:08.637Z","updated_at":"2026-06-30T12:02:09.656Z","avatar_url":"https://github.com/Prihod.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker MODX - Local Development Environment\n\nA ready-made solution for quick deployment of MODX in Docker containers. Perfect for local development of sites and extensions.\n\n## 🚀 Quick Start\n\nBefore starting, make sure you have [Docker](https://www.docker.com/get-started/) installed on your computer\n\nClone the repository into the project directory\n```bash\ngit clone \"https://github.com/Prihod/docker-modx.git\" ./\n```\n\nStart containers\n```bash\ndocker-compose up -d\n```\n\nView MODX installation log\n```bash\ndocker-compose logs -f php\n```\n\nThe first start can take a few minutes while MODX is unpacked and installed.\nDuring this time, the site can temporarily return `502 Bad Gateway`.\nWait until the `php` logs show `Modx installation is complete!` and `ready to handle connections`.\n\n### URL list\n\n| URL                      | Description                                   |\n|--------------------------|-----------------------------------------------|\n| http://localhost/manager | MODX Admin. Login: `admin`, Password: `admin` |\n| http://localhost:8080    | phpMyAdmin. Login: `modx`, Password: `modx`   |\n| http://localhost:8025    | MailHog                                       |\n| http://localhost:8181    | XHGui (optional)                              |\n\n## ✨ Main Features\n\n- Configurable PHP version\n- Automatic MODX installation/update\n- Data export/import with auto path correction\n- Database management through phpMyAdmin\n- Email testing via [MailHog](https://github.com/mailhog/MailHog)\n- Self-signed SSL certificate\n- SSH access\n- Xdebug support\n- Profiling through [Xhprof](https://www.php.net/manual/en/ref.xhprof.php) + [XHGui](https://github.com/perftools/xhgui)\n- Integration with [Blackfire](https://www.blackfire.io/php)\n\n## 🏗 Project Architecture\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Prihod/docker-modx/main/docs/images/architecture-dark.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/Prihod/docker-modx/main/docs/images/architecture-light.svg\"\u003e\n  \u003cimg alt=\"Architecture diagram\" src=\"https://raw.githubusercontent.com/Prihod/docker-modx/main/docs/images/architecture-light.svg\"\u003e\n\u003c/picture\u003e\n\n## 🗃️ Project Structure\n\u003cdetails\u003e\u003csummary\u003eShow structure\u003c/summary\u003e\n\n```\n.\n|-- .env\n|-- .gitignore\n|-- README.md\n|-- docker\n|   |-- logs\n|   |   |-- nginx\n|   |   `-- php\n|   |-- mariadb\n|   |   `-- conf\n|   |       `-- custom.cnf\n|   |-- modx\n|   |   |-- storage\n|   |   |   |-- backup\n|   |   |   `-- cache\n|   |   `-- tools\n|   |       `-- configurator\n|   |           |-- composer.json\n|   |           |-- config.inc.php\n|   |           |-- example.config.inc.php\n|   |           |-- run.php\n|   |           |-- src\n|   |           |   |-- Runner\n|   |           |   |   |-- Runner.php\n|   |           |   |   `-- RunnerInterface.php\n|   |           |   |-- Tasks\n|   |           |   |   |-- GrantAccessUserTask.php\n|   |           |   |   |-- InstallPackagesTask.php\n|   |           |   |   |-- MiniShop3Task.php\n|   |           |   |   |-- SetOptionsTask.php\n|   |           |   |   |-- Task.php\n|   |           |   |   |-- TaskInterface.php\n|   |           |   |   `-- TransportProvidersTask.php\n|   |           |   |-- Traits\n|   |           |   |   |-- DocumentTrait.php\n|   |           |   |   |-- ElementsTrait.php\n|   |           |   |   |-- InitializeTrait.php\n|   |           |   |   |-- OptionTrait.php\n|   |           |   |   |-- PropertiesTrait.php\n|   |           |   |   |-- SecurityTrait.php\n|   |           |   |   `-- TransportProviderTrait.php\n|   |           |   `-- Utils\n|   |           |       `-- Logger.php\n|   |           `-- storage\n|   |               `-- ms3\n|   |                   |-- pages\n|   |                   |   |-- cart.tpl\n|   |                   |   |-- category.tpl\n|   |                   |   |-- order.tpl\n|   |                   |   `-- thanks.tpl\n|   |                   `-- templates\n|   |                       |-- base.tpl\n|   |                       |-- cart.tpl\n|   |                       |-- catalog.tpl\n|   |                       |-- order.tpl\n|   |                       |-- product.tpl\n|   |                       `-- thanks.tpl\n|   |-- nginx\n|   |   |-- default.conf.template\n|   |   `-- ssl\n|   |-- php\n|   |   |-- Dockerfile\n|   |   |-- conf\n|   |   |   |-- opcache.ini\n|   |   |   |-- php.ini\n|   |   |   |-- xdebug.ini\n|   |   |   `-- xhprof.ini\n|   |   |-- sh\n|   |   |   |-- modx-clear-db.sh\n|   |   |   |-- modx-clear-site.sh\n|   |   |   |-- modx-configure.sh\n|   |   |   |-- modx-docker-start.sh\n|   |   |   |-- modx-download.sh\n|   |   |   |-- modx-export.sh\n|   |   |   |-- modx-generate-ssl.sh\n|   |   |   |-- modx-import.sh\n|   |   |   |-- modx-install.sh\n|   |   |   |-- modx-uninstall.sh\n|   |   |   `-- modx-upgrade.sh\n|   |   `-- xhprof\n|   |       |-- composer.json\n|   |       `-- handler.php\n|   |-- volume\n|   |   `-- mariadb\n|   `-- xhgui\n|       |-- Dockerfile\n|       |-- apache.conf\n|       |-- config.php\n|       `-- mongo.init.d\n|           `-- xhgui.js\n|-- docker-compose.override.blackfire.yml\n|-- docker-compose.override.xhprof.yml\n|-- docker-compose.yml\n`-- www\n```\n\u003c/details\u003e\n\n## 📦 PHP Extensions\n\n- GD, PDO, MySQLi\n- ImageMagick, PCNTL\n- Redis, OPcache, Fileinfo\n- Xdebug (optional)\n- Xhprof (optional)\n- Blackfire (optional)\n\n## 🎬 Video - Practical guide\n[![Practical guide](docs/images/video-cover.jpg)](https://youtu.be/8rZopEWS7ao)\n\n## 🖥️ Use Docker commands\n\n### Reinstall MODX\n```bash\nMODX_RESET=1 docker-compose up -d\n```\n\n### Export Data\n```bash\ndocker-compose exec php modx-export.sh\n```\nData is saved in `./docker/modx/storage/backup`\n\n### Import Data\n\nImport from latest archive\n```bash\nMODX_IMPORT=latest docker-compose up -d\n```\nImport from specific archive\n```bash\nMODX_IMPORT=\u003carchive_name\u003e docker-compose up -d\n```\nThe import archive should be located in the `./docker/modx/storage/backup` directory with the export file structure.\n\n### SSH-Access\n```bash\nssh dev@127.0.0.1 -p 2222  # Login: dev, Password: dev\n```\n\n## ⚙️ Configuration\n\nAll project settings are in the `.env` file. Below are the main parameters:\n\n| Name                         | Default Value | Description                                                                                                       |\n|------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------|\n| PHP_VERSION                  | 8.4           | PHP-FPM version                                                                                                   |\n| MODX_VERSION                 | 3.2.1-pl      | MODX version                                                                                                      |\n| MODX_INSTALL_ENABLE          | 1             | Automatically install MODX                                                                                        |\n| MODX_USE_CACHE_SOURCE        | 1             | Save MODX setup archive                                                                                           |\n| MODX_CONFIGURE_ENABLE        | 0             | Run configuration script after MODX installation                                                                  |\n| MODX_CONFIGURE_DEV_MODE      | 0             | Dev mode for MODX configuration script                                                                            |\n| MODX_TABLE_PREFIX            | random:8      | Database table prefix. When set to `random:number`, generates a random string with specified number of characters |\n| MODX_HTTP_HOST               | localhost     | Site hostname                                                                                                     |\n| MODX_LANGUAGE                | en            | MODX installation language                                                                                        |\n| MODX_CMS_ADMIN               | admin         | MODX administrator login                                                                                          |\n| MODX_CMS_PASS                | admin         | MODX administrator password                                                                                       |\n| MODX_IMPORT_DB               | 1             | Import MODX database                                                                                              |\n| MODX_IMPORT_SITE             | 1             | Import MODX files                                                                                                 |\n| MODX_EXPORT_DB               | 1             | Export MODX database                                                                                              |\n| MODX_EXPORT_SITE             | 1             | Export MODX files                                                                                                 |\n| MODX_EXPORT_OVERWRITE_CONFIG | 0             | Overwrite configuration files data during export with values from `MODX_EXPORT_...` variables                     |\n| XDEBUG_ENABLE                | 0             | Install Xdebug extension for PHP-FPM                                                                              |\n| XHPROF_ENABLE                | 0             | Install Xhprof extension for PHP-FPM                                                                              |\n| SSH_ENABLE                   | 1             | Enable SSH for `php` container                                                                                    |\n| SSL_GENERATE                 | 1             | Generate self-signed SSL certificate                                                                              |\n| NGINX_PORT                   | 80            | NGINX port                                                                                                        |\n| MARIADB_PORT                 | 3306          | MariaDB port                                                                                                      |\n| PHPMYADMIN_PORT              | 8080          | phpMyAdmin port                                                                                                   |\n| MAILHOG_PORT                 | 8025          | MailHog port                                                                                                      |\n| SMTP_PORT                    | 1025          | SMTP port                                                                                                         |\n| SMTP_HOST                    | mailhog       | SMTP host                                                                                                         |\n\n## 🔧 Advanced Features\n\n### MODX Auto-configuration\n\nWhen `MODX_CONFIGURE_ENABLE = 1`, the configuration script from `./docker/modx/tools/configurator/run.php` runs after installation.\n\nThe script executes tasks specified in the `config.inc.php` configuration file in the `tasks` option.\n\nWhen `MODX_CONFIGURE_DEV_MODE = 1`, after completing all tasks, MODX cache and logs won't be cleared, and the `./www/core/configurator` directory won't be deleted, allowing manual configuration script execution during development.\n\n```sh\ndocker-compose exec php bash \u0026\u0026 php /var/www/html/core/configurator/run.php\n```\n\n#### Available Configuration Tasks\n\n| Name                   | Key with options in config.inc.php | Description                                            |\n|------------------------|------------------------------------|--------------------------------------------------------|\n| TransportProvidersTask | transport_providers                | Adding transport providers                             |\n| InstallPackagesTask    | install_packages                   | Installing packages                                    |\n| SetOptionsTask         | set_options                        | Configuring system parameters                          |\n| GrantAccessUserTask    | grant_access_user                  | Setting up access rights                               |\n| MiniShop3Task          | ms3                                | Setting up miniShop3 store (optionally with demo data) |\n\n### Creating Custom Tasks\n\n1. Create a class in `./docker/modx/tools/configurator/src/Tasks`\n2. Inherit it from the `Task` class\n3. Implement `getName` and `execute` methods\n4. Add the task to `config.inc.php`\n\n### Example\n\nOutput all options from `config.inc.php` to MODX log:\n\n```php\n\u003c?php\n\nnamespace App\\Tasks;\n\nuse App\\Utils\\Logger;\n\nclass DemoLogTask extends Task\n{\n    public function getName(): string\n    {\n        return 'Demo log';\n    }\n\n    public function execute(): void\n    {\n        Logger::info(\"Start execute my task!\");\n        $this-\u003emodx-\u003elog(\\modX::LOG_LEVEL_ERROR, print_r($this-\u003egetProperties(), 1));\n        Logger::info(\"Finish execute my task!\");\n    }\n}\n```\n\n## 🛠 Developer Tools\n\n### Xdebug\n```env\nXDEBUG_ENABLE=1\n```\n\n### Xhprof + XHGui\n```env\nXHPROF_ENABLE=1\n# + rename docker-compose.override.xhprof.yml to docker-compose.override.yml\n```\n\n### Blackfire\n```env\nBLACKFIRE_ENABLE=1\nBLACKFIRE_CLIENT_ID=\u003cclient_id\u003e\nBLACKFIRE_CLIENT_TOKEN=\u003cclient_token\u003e\nBLACKFIRE_SERVER_ID=\u003cserver_id\u003e\nBLACKFIRE_SERVER_TOKEN=\u003cserver_token\u003e\n# + rename docker-compose.override.blackfire.yml to docker-compose.override.yml\n```\n\n### ⚠️ Note\n\nWhen changing configuration, rebuild the container:\n\n```bash\ndocker-compose build --no-cache php\n```\n\n### Troubleshooting: `Error 503 - Could not load MODX config file`\n\nThis error means MODX installation did not finish, so `core/config/config.inc.php` was not created.\n\n1. Rebuild the `php` container (required after updating startup scripts):\n    ```bash\n    docker-compose build --no-cache php\n    ```\n2. Start containers and watch installation logs:\n    ```bash\n    docker-compose up -d\n    docker-compose logs -f php\n    ```\n3. Wait for these lines in logs:\n    - `Modx installation is complete!`\n    - `ready to handle connections`\n4. If needed, force a clean reinstall:\n    ```bash\n    MODX_RESET=1 docker-compose up -d\n    ```\n\n## Main Docker and Docker Compose Commands\n| **Command**                                             | **Description**                                                                          |\n|---------------------------------------------------------|------------------------------------------------------------------------------------------|\n| **Docker**                                              |                                                                                          |\n| `docker ps`                                             | Shows running containers.                                                                |\n| `docker restart \u003ccontainer_id\u003e`                         | Restarts a container.                                                                    |\n| `docker logs \u003ccontainer_id\u003e`                            | Shows container logs.                                                                    |\n| `docker exec -it \u003ccontainer_id\u003e bash`                   | Opens terminal inside container.                                                         |\n| `docker system prune`                                   | Removes unused data (containers, images, volumes, networks).                             |\n| **Docker Compose**                                      |                                                                                          |\n| `docker-compose up`                                     | Starts all services specified in `docker-compose.yml`.                                   |\n| `docker-compose up -d`                                  | Starts services in background mode.                                                      |\n| `docker-compose down`                                   | Stops and removes services, networks, volumes created by `up`.                           |\n| `docker-compose restart`                                | Restarts all services.                                                                   |\n| `docker-compose ps`                                     | Shows list of running services.                                                          |\n| `docker-compose logs`                                   | Shows logs of all services.                                                              |\n| `docker-compose logs --tail \u003cnumber\u003e`                   | Shows last `\u003cnumber\u003e` lines of logs for all services.                                    |\n| `docker-compose logs -f \u003cservice_name\u003e`                 | Shows and follows log stream for specified service.                                      |\n| `docker-compose logs -f --tail \u003cnumber\u003e \u003cservice_name\u003e` | Shows and follows log stream for specified service, starting from last `\u003cnumber\u003e` lines. |\n| `docker-compose exec \u003cservice_name\u003e bash`               | Opens terminal inside specified service.                                                 |\n| `docker-compose build`                                  | Builds images for services from `docker-compose.yml`.                                    |\n| `docker-compose build --no-cache`                       | Builds images without using cache.                                                       |\n| `docker-compose build --no-cache \u003cservice_name\u003e`        | Builds image for specified service without using cache.                                  |\n| `docker-compose top`                                    | Shows processes running in services.                                                     |","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprihod%2Fdocker-modx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprihod%2Fdocker-modx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprihod%2Fdocker-modx/lists"}