search

PMET-public / mdm

3 stars 1 forks source link

readme

Overview

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:

  1. End users who might use the Magento app for demos, testing/QA, or training
  2. 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

MDM 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

Top Level Menu Items
⚠️▶️ Docker not installed. Click for download. link Complete the install by running Docker for the 1st time to reveal more menu items.
▶️ Finish Docker install by running for the 1st time. 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.
▶️ Start Docker to continue Docker is not running. Start it.
⚠️ Missing credentials - features limited 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.
⚠️ Credentials found but invalid 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
⚠️🔼 Can't install - ports in use. 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.
▶️ Restart Magento app
⚠️▶️ Can't restart app - ports in use.
🚨 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

💻 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

Top Level Menu Items
📝 Open MDM logging Advanced Watch the MDM output in realtime. Combine with MDM debugging under Maintenance
                          

📱 PWA

📱 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

Top Level Menu Items
⚠️ Can't run PWA - ports in use. A local service is already using the required ports.
                          

🚑 Help / Support

🚑 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

🎗 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

📝 Logs Advanced
Show errors from MDM log Show just the recorded errors
Follow MDM logs
Show Magento app logs
                          

🛠 Maintenance

🛠 Maintenance Advanced
🐞 PHP Xdebug is ON|OFF for this app Turn on off php debugging
🐞 MDM debugging is ON|OFF for this app Turn on off debugging of MDM - much more info written to the logs
Force check for new MDM version
Revert to previous MDM
⚠️ 🔓 Permit spoofing ANY domain is ON|OFF! 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.
⚠️ Prune all non-running containers and volumes Deletes ANY installation that is not ACTIVELY RUNNING. This will remove any installation that you can not currently browse.
⚠️ Prune everything EXCEPT images 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

Top Level Menu Items
💡Advanced mode is ON|OFF (v. $v) Show more advanced menu items and display the current version of MDM
                          

Frequently Asked Qestions (FAQ)

"How do I spoof domains?" or "Why is my certificate invalid?"

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.

"What is the default admin username and password?"

The values are inherited from the Magento Cloud Docker project here

"How do I setup and where do I place my auth.json file?"

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.

"What's auth.json used for?"

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.)

"What does this error mean?"

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.

"How do I upgrade WITHOUT preserving old installations? (i.e. start over)"

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.

Prebuilt Apps Instructions & FAQ

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.

Frequently Asked Questions

What's the difference between the "bundled-new" apps and the "cloned" apps?

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.

What is MDM-lite?

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:

Certs FAQ

How MDM creates/retrieves & stores certs

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.comare 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.

How MDM handles certs with a fallback strategy

  1. MDM will first look for a current, valid, existing cert in the hostname dir.
  2. 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.
  3. If the hostname and wildcard certs are not available, then MDM will create one in the hostname dir with mkcert (if enabled).
  4. If mkcert is not enabled, then an invalid cert created for localhost will 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.

The preferred order explained

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.

(Re)starting new web services

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.

MDM Developers

Recommended IDE & Extensions

IDE: VSC

IDE Extensions:

  1. Bash Debug
  2. BASH IDE
  3. Bats
  4. shellcheck

The included .vscode/launch.json has some useful debug scenarios pre-configured that you can use to step through.

Development on a Mac

1. clone this repo

$ git clone https://github.com/PMET-public/mdm.git && cd mdm

2. configure additional features

$ cp .mdm_config.tmpl.sh .mdm_config.sh

3. set up your env

$ export debug=1 MDM_REPO_DIR=. COMPOSER_AUTH='{"github-oauth":{"github.com":"..."}}'

4. run the launcher

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"

Development of this project itself

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

Additional troubleshooting notes

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.

Application Configuration For Development

Configuration of MDM

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

Configuration of an MDM app

Running tests

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.

Debugging

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.

Publishing releases

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.

Updating the README for menu updates

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.