- Overview
- MDM End Users
- Top Level Menu Items
- 💻 Magento commands
- Top Level Menu Items
- 📱 PWA
- Top Level Menu Items
- 🚑 Help / Support
- 🎗 Useful resources
- 📝 Logs
- 🛠 Maintenance
- Top Level Menu Items
- Frequently Asked Qestions (FAQ)
- "How do I spoof domains?" or "Why is my certificate invalid?"
- "What is the default admin username and password?"
- "How do I setup and where do I place my auth.json file?"
- "What's auth.json used for?"
- "What does this error mean?"
- "How do I upgrade WITHOUT preserving old installations? (i.e. start over)"
- Prebuilt Apps Instructions & FAQ
- Frequently Asked Questions
- Certs FAQ
- MDM Developers
Screenshots of the MDM UI on a Mac (left) and on any terminal - Mac/Linux/Windows (right).
| OSX Menu App | CLI Menu App |
|---|---|
 |
 |
Magento Docker Manager (MDM) is a cross platform (Mac/Linux/Windows) application to run multiple, simultaneous Magento applications on your local system via Docker. Once installed, simply select options from the available menu items to manage your applications.
MDM's menus are contextual. Only applicable options are shown. For example, if a tool is not installed, you will be prompted to install it before continuing to unlock a feature. If the application is stopped, you'll be prompted it to start it for additional menu options.
MDM has 2 general audiences:
- End users who might use the Magento app for demos, testing/QA, or training
- Developers who want to develop/test locally on a Magento Cloud like env or want to configure a packaged app for their team of end users
End users experience MDM almost entirely through the contextual menus. Below is every possible menu item (in the order they would appear if they are applicable) with some additional notes if appropiate. If you do not see a particular menu item, then MDM has determined it's not currently appropiate. Many items only become available after toggling Advanced mode on.
| Top Level Menu Items | ||
|---|---|---|
| link | Complete the install by running Docker for the 1st time to reveal more menu items. | |
| Finish the install by running Docker for the 1st time and revealing more menu items. | ||
| 🔼 Install added tools for more features | Highly recommended - includes the magento-cloud CLI, mkcert, tmate, platypus, docker CLI completion | |
| 🎚 Adjust Docker for min reqs | Update the docker vm settings for better performance. | |
| Docker is not running. Start it. | ||
MDM can not find your ~/.composer/auth.json file. You won't be able to create new apps from source or use features tied to your GitHub org configuration, but a prepackaged app will work. The link to doc shows how to create it. |
||
Your ~/.composer/auth.json file exists, but the JSON contents aren't parsing correctly OR it doesn't have the required GitHub token & Magento keys. Please verify its contents. |
||
| 👉 🔄 Update MDM 👈 | There is a new version of MDM available. Under Maintenance, there is an option to revert if needed. | |
| 🔼 Install & open Magento app | ||
| Some local service other than docker is using port 80 or 443. | ||
| 🚀 Open https://$(get_hostname_for_this_app) | Opens your browser to the app's base url. The menu will render the base url instead of the function call. You'll actually see something like: '🚀 Open https://mysite.com' | |
| 🛑 Stop Magento app | If not actively being using, stopping the app will free memory. | |
| 🚨 Uninstall this Magento app | If an error occurred during install, this option allows you to try again. | |
| 🛑 Stop all other Magento apps | While multiple Magento apps can run at the same time, it may consume many resources. | |
| 📦 Create new MDM app | Asks for a Magento Cloud project to recreate locally | |
| ☁️→💻 Sync FROM cloud env | ||
| 💻→☁️ Sync TO cloud env | ||
| 💻 Magento commands | ||
|---|---|---|
| 🛑 App stopped. Many cmds N/A | Start Magento to reveal more options | |
| 💻 Start shell in app | ||
| Reindex | ||
| Run cron jobs | ||
| Enable all except cms cache | ||
| Enable all caches | ||
| Flush cache | ||
| Warm cache | ||
| Pre-generate resized catalog images | ||
| Change url for app | Use ANY url for your app. Combine with certificate spoofing for better browser compatibility. | |
| 💻 Start MDM shell | Advanced See the status of your Docker services | |
| Top Level Menu Items | ||
|---|---|---|
| 📝 Open MDM logging | Advanced Watch the MDM output in realtime. Combine with MDM debugging under Maintenance | |
| 📱 PWA | ||
|---|---|---|
| 📱 This app | The PWA will use the local Magento app as the backend. | |
| 🛑 App stopped. Start PWA offline | ||
| 📲 Choose your own | ||
| 🎗 PWA @ GitHub | link | |
| Top Level Menu Items | ||
|---|---|---|
| A local service is already using the required ports. | ||
| 🚑 Help / Support | ||
|---|---|---|
| Magento Org #m2-demo-support | link | link to slack channel |
| 💻 Grant remote access to system | Only remote users with pre-authorized keys will be able to connect 1 time. If not configured, a warning appears. Choose if you want to continue and provide the secret url to a remote user. | |
| 🛑 Stop remote system access | ||
| 🔓 Grant remote web access | If configured, creates a public url able to access this Magento app. | |
| 🛑 Stop remote web access; revert url | ||
| Magento Community #cloud-docker | link | link to slack channel |
| Offical Cloud Support | link | |
| 🎗 Useful resources | ||
|---|---|---|
| MDM @ GitHub | link | This project |
| Docker Folder (OneDrive) | link | |
| SI Team Home Page (SharePoint) | link | |
| Docker development @ devdocs | link | The project that MDM builds on to mimic Magento Cloud services |
| Your Magento Cloud Projects | link | |
| Magento Cloud Chrome Extension | link | |
| Inside Adobe | link | |
| Field Readiness | link | |
| 📝 Logs | Advanced | |
|---|---|---|
| Show errors from MDM log | Show just the recorded errors | |
| Follow MDM logs | ||
| Show Magento app logs | ||
| 🛠 Maintenance | Advanced | |
|---|---|---|
| 🐞 PHP Xdebug is ON|OFF for this app | Turn on | |
| 🐞 MDM debugging is ON|OFF for this app | Turn on | |
| Force check for new MDM version | ||
| Revert to previous MDM | ||
| Create TLS certificates that are valid locally for any domain. Do not share your local CA! | ||
| 🔄 Reload reverse proxy | ||
| 🧹 Remove hosts added to /etc/hosts | ||
| 🧹 Prune all unused docker images | Removes old or currently unused Docker images. If no apps are currently installed, Docker will re-download the required images during installation. | |
| Deletes ANY installation that is not ACTIVELY RUNNING. This will remove any installation that you can not currently browse. | ||
| This will delete ALL docker containers, volumes, and networks. ONLY Docker images will be preserved to avoid re-downloading images for new installations. | ||
| 🚨 Wipe Docker (removes ALL Docker artifacts) | Use this to wipe the Docker virtual machine of all data. Only modified Docker VM settings will be preserved. | |
| Top Level Menu Items | ||
|---|---|---|
| 💡Advanced mode is ON|OFF (v. $v) | Show more advanced menu items and display the current version of MDM | |
By default, the option to "spoof" (mimic) any domain is disabled. You should not enable it on a computer that you share or allow others access too. If a malicious user gains access to your system, they might use it to spoof legitimate domains. With that caveat, it's still very useful. To enable it, enable advance mode, then go to the maintenance menu, then toggle the spoofing option on.
The values are inherited from the Magento Cloud Docker project here
Follow the instructions here with 1 clarification: place your auth.json file in your ~/.composer/ directory so the full, explicit path will be: /Users/<yourusername>/.composer/auth.json on OSX or /home/<yourusername>/.composer/auth.json on Linux systems.
Note for OSX users: You will not see the .composer dir in your user (Home) dir in Finder unless you press ⌘ (command) + shift + . (dot). Also be careful that the editor used to create your auth.json file does not insert special characters (e.g. curly quotes for double quotes). MDM will attempt to validate the format of auth.json and report if it detects such errors.
You may have downloaded or received a pre-bundled app with all the required modules, but if you need/want to run composer update to get future updates OR you want to create your own app, you will need an auth.json file. Also the GitHub token in the auth.json file is used to configure/download additional features of MDM (e.g. valid wildcard TLS certificates, web tunneling, etc.)
Whichever error you encounter, please check (i.e. search) to see if your issue has already been reported and possibly solved. If not, please open a new one.
In a terminal, run rm -rf ~/.mdm and the follow any instructions from the MDM menu afterward. Then ensure advanced mode is toggled on to see the maintenance menu. From the maintenance menu, prune everything except images. The Docker VM is now cleaned from old installs, and you can also remove any old MDM apps from the host computer.
DO NOT DOWNLOAD APPS FROM THE ONEDRIVE WEB UI. USE FINDER. - Currently, OSX prevents apps downloaded via the web UI from running. We are looking into possible solutions.
Copy any MDM app from your synced OneDrive folder to another local folder like Downloads or Documents.
Double click the local app and look for the Magento icon in your menu bar.
The "bundled-new" apps have all the composer dependencies bundled with them and will install a new Magento store from the beginning. No composer credentials are required to run, but they will be required to update.
The "cloned" apps represent a snapshot of sample Magento install just after installation has completed. Credentials will be required to run, but because it is a snapshot of an already installed app, the initial start up will be MUCH faster.
It's a version of MDM with no associated Magento application, so it downloads from OneDrive and starts up almost instantly.
Despite no associated app, MDM-lite still has several uses such as:
- cloning your existing envs instead of using one of the pre-made, generic apps.
- running PWA against remote back-ends
- getting support access for your local systme
Certs for a hostname are stored in a directory of the same name. For example, certs for test.example.com are stored in ~/.mdm/certs/test.example.com/
Wildcard certs are stored in a directory minus the leading "*". For example, certs for *.exmple.com are stored in ~/.mdm/certs/.example.com
A user can add existing Let's Encrypt certs in these dirs, or set up a system to automatically deploy/retrieve certs to those direcorties much like the MDM demo domain for the Magento team.
- MDM will first look for a current, valid, existing cert in the hostname dir.
- If valid hostname cert is not available, MDM will look for a valid wildcard cert dir. If that exists, it will be copied to the hostname dir.
- If the hostname and wildcard certs are not available, then MDM will create one in the hostname dir with
mkcert(if enabled). - If
mkcertis not enabled, then an invalid cert created forlocalhostwill be used. Browsers will show the site as invalid but will likely allow the user to proceed. In Chrome, to bypass invalid certs, the user must type "thisisunsafe" in the site's tab.
Let's Encrypt are real certs that should be accepted by all browsers on all hosts. Certs from mkcert are only valid on the host with the CA installed, and while they are valid for 10 yrs, more browsers are choosing to reject very long lived certs. mkcert also imposes additional responsibility on the user. If the user's CA is compromised, a "valid" spoofed cert may be created for a malicious web service attempting to steal credentials. While unlikely that the CA would be compromised without the rest of the user's system also being compromised, the user should understand this risk.
Each time a new web service is added (or an existing one restarted), MDM will check that every found web service hostname resolves to 127.0.0.1 (a.k.a. localhost) and that a cert is provided by the fallback strategy outlined above. Then MDM will dynamically create the necessary nginx config for each service to be handle by the reverse proxy listening on local ports 80 & 443.
IDE: VSC
IDE Extensions:
The included .vscode/launch.json has some useful debug scenarios pre-configured that you can use to step through.
$ git clone https://github.com/PMET-public/mdm.git && cd mdm
$ cp .mdm_config.tmpl.sh .mdm_config.sh
$ export debug=1 MDM_REPO_DIR=. COMPOSER_AUTH='{"github-oauth":{"github.com":"..."}}'
The launch script controls both the platypus GUI and the CLI. For this reason, arguments must be fed to the launch script as strings.
$ ./bin/launcher
Install missing requirements on this computer
$ ./bin/launcher "Install missing requirements on this computer"
As you're making changes to the scripts, copy them to the ~/.mdm dir like such:
rsync --exclude='.git/' -avz . ~/.mdm/0.0.0-dev; ln -sfn ~/.mdm/0.0.0-dev ~/.mdm/current
To debug the launching script, run export debug_launcher=1, too. This is currently a separate var because the launching script debug output would otherwise display (and disrupt) the menu output before the logging initialization can run. Also, the launching script debug output (bundled with each app) is the output of the app's <osx_appp>/Contents/Resources/script, not the output of ~/.mdm/current/launcher. The launcher should not need to be debugged often because it's relatively minimal, stable code to bootstrap the app.
| Feature | Config Param |
|---|---|
| Public Certs | mdm_domain |
mdm_domain_fullchain_gh_url |
|
mdm_domain_privkey_gh_url |
|
| Remote Support/Access | mdm_tmate_authorized_keys_url |
| Public Web Access | mdm_tunnel_domain |
mdm_tunnel_ssh_url |
|
mdm_tunnel_pk_url |
MDM uses Bats for testing. You'll find all tests in the numbered subdirectories of tests.
Example #1: Call all tests in all immediate subdirectories of the specified one and show test timings.
./tests/libs/bats/bin/bats -T ./tests/1-generic-lib-and-non-app-specific/**/*.bats
Example #2: Call all tests recursively for the specified dir and show test timings.
./tests/libs/bats/bin/bats -T -r ./tests/2-dockerize-then-run-detached-app
See .gitub/workflows for additional example invocations.
A VSCode launch file (.vscode/launch.json) containing many debugging examples is included. Stepping through example debug configurations is a great way to become familiar with the control flow of MDM.
MDM checks the releases page for the version of the most recent release. If that release is a newer semantic version, the user will be prompted to update. This system will need to be updated at some point if there are multiple major & minor releases.
Part of this README is auto generated by script. When menu items are changed, the script should be re-run and the output paste into this file.