The Mage-OS distribution is here. It was released early October 2023 and it has seen a steady growth of installs. I got started with it myself, encountered some issues and found it fun to blog about. Here it is.
Composer installation
A fresh new installation of Mage-OS is easily started with a simple command:
composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition .
Run the composer install, run the Magento install. And if you are just setting up a plain Magento install to test things, this should be it. There were some issues with the sample data, with images missing - but I heard this should have been solved already.
Composer replacements
Whenever I install Magento, I see hundreds of modules of which I only need a fraction. So I usually chuck out more than half of them, by using the Magento composer replacements I have been maintaining for some time now. Nowadays, I do this with just a few commands by using the new Magento Composer Replacement Tool.
However, those replacements were for magento/* packages. And with the Mage-OS distribution, all composer names are rewritten to mage-os/. A fix in my replace tools was added during a Meet Magento NL hackathon and with that, the replacements are flawless under the Mage-OS distribution as well. A lightweight Mage-OS distro.
Magerun update
When using the Magerun2 CLI on the Mage-OS distro, it fell apart. There was a manual check to determine whether the current folder contained a valid Magento installation and this was done by scanning for the magento2-base package. However, in the summer, Christian - the main guy behind Magerun - already provided a fix for this. Next, I spent half an hour on upgrading Magerun (due to weird Docker volume caching issues in my own environment) but that solved it in the end. Magerun works fine, Jisse does not.
Other extensions just work
I personally found any other Magento extension to be working without issues - thanks to the composer replacements of Mage-OS. Tools like AvS ScopeHint2, MSP DevTools and a couple of my own Yireo extensions were added quickly.
Upgrading projects
Upgrading existing Magento projects to Mage-OS is a bit more cumbersome: It starts with updating root composer.json with new ones. For instance, magento/product-community-edition is replaced with mage-os/product-community-edition. But there is more. Make sure to spend sufficient time on this: Look for changes in the package names and the versions. I tries this a couple of times too quickly and found myself with lots of composer upgrade errors. What I did a couple of times is install a fresh Mage-OS project (composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition), take its composer.json file and compare it line-by-line with the composer.json file I was trying to upgrade. Good luck.
Magento Admin Panel issues
Once the upgrade of Magento to Mage-OS (or should I call it a migration) is done, my Magento Admin Panel had huge issues. In the end I wiped out all browser storage, incl localStorage, cookies and cache. And this solved things.
PHPStorm Magento plugin
One annoying issue I still have is that the Magento plugin in PHPStorm (which is excellent for navigating through XML files, plus generating files) is no longer detecting the Mage-OS environment as a valid Magento installation. Still need to dive into that.
Hope this helps someone else!
About the author
Jisse Reitsma is the founder of Yireo, extension developer, developer trainer and 3x Magento Master. His passion is for technology and open source. And he loves talking as well.
