FAQ about Mage-OS at maxcluster

What is Mage-OS?

Mage-OS is a fork of Magento 2. In order to become more independent from Adobe, https://mage-os.org was developed from the community.

Hereby a Magento distribution was created, which allows to install Magento without an Adobe account. In addition, the initiative plans to offer its own fork in the short term, which should, however, remain largely compatible with Magento 2.

Detailed information can be found here: https://mage-os.org/organization/about.

Can I use my maxcluster cluster with Mage-OS?

We have created a so-called mirror, with which we support Mage-OS for every version from Magento 2.3.7-p3. So you don't have to pay attention to any special features here.

In the Managed Center, however, we offer separate selection options for Mage-OS in some places, such as the NGINX template, in order to be able to react better to future deviations from Magento, if necessary.

Also our command line tools like mc-software are already compatible for Mage-OS; the same is true for ShopPerformance and ShopSecurity.

If you have any questions about our servers, please feel free to contact us as usual at support@maxcluster.de.

How do I install Mage-OS?

In the following, we explain how to install the Magento distribution Mage-OS at maxcluster.

At the current state, it is possible to install the "mirror" distribution using these instructions.

In addition, Mage-OS plans to offer a fork with its own customizations this year. Of course, we will then expand this guide accordingly.

Preparations

First, create a new vHost in the maxcluster interface. This can be done in the menu item "Apache" or "NGINX".

Apache: For the current version Mage-OS 2.4.5 please set PHP 8.1 here.

NGINX: For NGINX, please also select the Magento 2 application template.

After the release of a Mage-OS fork, we will provide a separate template for it.

Additionally a database is needed, which can be created at maxcluster under Database and Search → MySQL.

In addition, an OpenSearch or an Elasticsearch instance is also required. For MageOS 2.4.5 we recommend to use OpenSearch version 1.2.

The installation of the instances can be done conveniently at maxcluster via the menu item "OpenSearch".

Please note: After the installation you still have to create a new instance.

Download

The actual installation is done in the next step via SSH. The necessary access data for this is available in the Managed Center under "SSH".

Note: If a CI/CD pipeline or deployment tool is to be used, the installation can also be performed outside the cluster. However, in these instructions, we assume that the installation is performed on the cluster itself.

First, please change to the folder where Magento is to be placed. Please note: For Apache, this should not be the document folder "root (htdocs)".

cd /var/www/share/mage-os.c-421.maxcluster.net

After that, please install Mage-OS via composer with the following command:

composer2 create-project --repository-url=https://mage-os.maxcluster.net/mirror/ magento/project-community-edition magento

The last command specifies the folder where Magento should be installed.

In the case shown, the Mage OS mirror provided by maxcluster is provided. Alternatively, another mirror can be used. An overview of the possible mirrors is available on the Mage-OS homepage: https://mage-os.org/distribution

Installation

Now the actual installation takes place.

For this, please first change to the Magento folder.

cd magento

Then perform the installation using /bin/magento durch.

With the command

./bin/magento setup:install --help

you can see all possible parameters.

In our example the installation is done with this command:

./bin/magento setup:install \ --base-url=https://mage-os.c-421.maxcluster.net/ \ --db-host=localhost \ --db-name=db-1 \ --db-user=db-user-1 \ --db-password=... \ --admin-firstname=max \ --admin-lastname=muster \ --admin-email=admin@admin.com \ --admin-user=admin \ --admin-password=admin123 \ --language=de_DE \ --currency=EUR \ --timezone=Europe/Berlin \ --use-rewrites=1 \ --search-engine=elasticsearch7 \ --elasticsearch-host=127.0.0.1 \ --elasticsearch-port=9500 \ --backend-frontname=secret

So that the installation can be called afterwards, please set a symlink to the document root of the web server.

To do this, please delete the previous htdocs folder

rm -rf ~/mage-os.c-421.maxcluster.net/htdocs/

and link the pub folder.

Please note: For NGINX, please link the magento folder instead of the pub folder, since the NGINX template already ensures that the pub folder is delivered.

ln -s ~/mage-os.c-421.maxcluster.net/magento/pub/ ~/mage-os.c-421.maxcluster.net/htdoc

Afterwards, please restart PHP via the maxcluster Managed Center - or for automated deployments with Cluster-Control.

You can now see an empty Magento installation in the browser:

Finally, please install the Magento cronjob using this command:

Optimizations

Please note: The Magento instance installed in this way is not yet ready for production use, so it should definitely be put into product mode first:

bin/magento deploy:mode:set production

Afterwards the static files have to be recreated:

rm -rf pub/static/adminhtml/ rm -rf pub/static/frontend/ bin/magento setup:static-content:deploy

Note: If not all data needs to be available in real time, the Magento indexer can be switched to "schedule" mode. This is also possible for individual indexes. The following command will switch all indexers accordingly:

bin/magento indexer:set-mode schedule

At the end of a deployment, we recommend optimizing the autoloader to further optimize the load time.

composer2 dump-autoload -o --apcu

Via bin/magento you can also set various settings for Magento. This is of course also possible via the Magento backend.

bin/magento config:set system/smtp/set_return_path 2 bin/magento config:set system/smtp/return_path_email support@musterfirma.de

For a productive environment we recommend to set the following settings:

bin/magento config:set dev/js/minify_files 1 bin/magento config:set dev/css/minify_files 1 bin/magento config:set web/seo/use_rewrites 1

In a next step we recommend integrating Varnish additionally. We have documented instructions for integration in our blog.

Finally, you can use the ShopPerformance tool to check whether further optimizations are possible.

Switching between Mage-OS and Magento 2

It is possible to switch between Mage-OS and Magento 2. For this, it is sufficient to adjust the repository in composer.json accordingly:

For Magento 2:

"repositories": [ { "type": "composer", "url": "https://repo.magento.com/" } ],

For the maxcluster Mage OS mirror:

"repositories": [ { "type": "composer", "url": "https://mage-os.maxcluster.net/mirror/" } ],

For the official Mage OS mirror:

"repositories": [ { "type": "composer", "url": "https://mirror.mage-os.org/" } ],