About the Mage-OS Distribution

Mage-OS is an upstream compatible, lightweight composition of Magento Open Source packages. Some packages will contain changes, and some will be entirely new. We aim to keep the Mage-OS Distribution compatible with all existing Magento 2 extensions and integrations to the greatest extent possible.

What differentiates Mage-OS from Magento Open Source and Adobe Commerce?

  • Independent and community-driven
  • More accessible to new users, developers, and contribution
  • Lightweight package selection by default
  • Simple migration to and from Magento Open Source

Read our product vision for the Mage-OS Distribution

Installing Mage-OS

You can create a new Mage-OS project with the following command:

composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition .

After a successful composer download, you will need to run the installer. Please see DevDocs: Installation Guide for Mage-OS

Moving to Mage-OS

If you are already using Magento 2.4 and PHP 8.1+, you can change to Mage-OS by running the following in SSH:

composer config repositories.0 composer https://repo.mage-os.org/ && \
    composer require mage-os/product-community-edition --no-update && \
    composer remove magento/product-community-edition magento/composer-dependency-version-audit-plugin magento/composer-root-update-plugin --no-update && \
    composer remove sebastian/comparator --dev --no-update && \
    composer update --no-plugins --with-all-dependencies

We strongly recommend updating to the latest Magento version (currently 2.4.6-p3) before changing to Mage-OS, to minimize issues.

Your specific situation may require additional changes to your composer.json file. Generally this will involve changing magento/ package names to mage-os/, or updating dependency versions.

Magento™ Mirrors

You can obtain Magento packages through these Mage-OS-built Magento mirror repositories for composer:

These can be used to install Magento Open Source 2.3.7 and 2.4.x without authentication. To install magento/project-community-edition 2.4.6-p3 in your working directory, for example:

composer create-project --repository-url=https://mirror.mage-os.org/ magento/project-community-edition:2.4.6-p3 .

Magento™ Nightly Builds

For the first time ever, you can install a nightly build of Magento’s latest published development source code, without having to wait for an official beta release. Mage-OS’s upstream-nightly composer repository is updated each day with the latest code from the Magento github.

We hope this will be useful for vendors and extension providers to track compatibility of their products with upcoming releases.

Keep in mind that the nightly release might be broken sometimes, depending on the state of the code in the upstream Magento git repositories.

To install our latest nightly build of Magento Open Source in your working directory:

composer create-project --stability alpha --repository-url=https://upstream-nightly.mage-os.org magento/project-community-edition .

Repository Generation

You can create your own Magento mirror or Mage-OS/Magento-based release with self-built packages, using the repository generator found at github.com/mage-os/generate-mirror-repo-js.

Generating from scratch takes about 1.5 hours on a low-end server (2G RAM, no swap). We are actively improving the tool to make it faster and more usable, however, we expect alternative implementations to be the primary tooling in the future for performance reasons. The current JavaScript-based implementation was started as a research project into minimizing dependencies.

If you publish a mirror, please let us know to add it to the list above!

Developer Documentation

Mage-OS is currently undertaking a complete re-write of the Magento Open Source Developer Documentation (DevDocs).

If you are looking for technical guidance on the platform you will find it here:
https://devdocs.mage-os.org/docs/main
https://github.com/mage-os/devdocs/

If you would like to help with this project please get involved!

Roadmap

Mage-OS is community maintained and community developed, so to some extent the direction depends on what people contribute.

Our first priority is to get an independent distribution live, then iterate on that to improve simplicity and performance in a backwards-compatible way.

Stay tuned, or start contributing to help set the roadmap!