Installing Mage-OS on Ubuntu

What Mage-OS is

Mage-OS is an independent, non-profit distribution of Magento Open Source maintained by the community. Mage-OS 3 is built on Magento Open Source 2.4.9, so themes and extensions that work on 2.4.9 generally work on Mage-OS 3.

• No access keys: the Composer repository is public. You do not need an Adobe account to install it.
• Fast security releases: Mage-OS 3.5.0 (8 September 2026) was an emergency release that brought Adobe's fix for a critical remote code execution flaw within days.
• Same code base: modules, the admin and the database structure are those of Magento 2.4.9.

Requirements

The server preparation is the same as for Magento 2.4.9. Follow the Magento 2.4.9 on Ubuntu guide for the server, Ubuntu, tuned-adm and services, then come back here for the download.

Choosing a server

Size the server for search, indexing and checkout, not for the homepage. A catalogue of 50,000 products needs memory for OpenSearch and the database long before the storefront feels slow.

• VPS or dedicated: a good VPS is enough for most stores. Choose dedicated hardware when you need guaranteed CPU at peak times.
• Location: pick a data centre close to your customers. Frankfurt or Amsterdam for Germany and most of Europe, Istanbul for Türkiye, London for the UK.
• Disk: NVMe only. Magento reads and writes many small files and the database is disk-heavy during indexing.
• Backups: snapshots from the provider are not a backup plan on their own. Keep daily database dumps and media copies in a second location.

Downloading Mage-OS

cd /var/www
composer create-project \
  --repository-url=https://repo.mage-os.org/ \
  mage-os/project-community-edition mageos

Installing Mage-OS

The installer is the same as Magento's:

cd /var/www/mageos
bin/magento setup:install \
  --base-url=https://www.example.com/ \
  --db-host=localhost --db-name=mageos --db-user=mageos --db-password='change-this-password' \
  --admin-firstname=Admin --admin-lastname=Store --admin-email=you@example.com \
  --admin-user=youradmin --admin-password='a-long-unique-password' \
  --backend-frontname=a-private-admin-path \
  --search-engine=opensearch --opensearch-host=127.0.0.1 --opensearch-port=9200 \
  --session-save=redis --session-save-redis-host=127.0.0.1 --session-save-redis-db=2 \
  --cache-backend=redis --cache-backend-redis-server=127.0.0.1 --cache-backend-redis-db=0

bin/magento deploy:mode:set production
bin/magento cron:install
bin/magento indexer:set-mode schedule

Then follow the same after-installation steps as for Magento: Varnish, session locking, two-factor login, mail and backups.

Moving from Magento to Mage-OS

Because Mage-OS 3 is built on Magento 2.4.9, moving a 2.4.9 store is a change of Composer packages, not a rebuild. Stores on older versions upgrade to the matching level first.

1. Make a full backup of code, database and media, and work on a staging copy.
2. Check every extension against Magento 2.4.9 / Mage-OS 3.
3. Switch the Composer repository and the meta-package to Mage-OS, then run composer update.
4. Run bin/magento setup:upgrade, compile and deploy static content.
5. Test checkout, payments, e-mails and integrations before switching the live store.

tuned-adm and server tuning

tuned is a Linux service that applies a set of kernel and system settings for a type of workload: CPU frequency behaviour, disk scheduling, memory and network parameters. You pick one profile, tuned applies it and keeps it after a reboot.

apt install -y tuned
systemctl enable --now tuned
tuned-adm recommend          # what tuned suggests for this machine
tuned-adm profile virtual-guest
tuned-adm active
tuned-adm verify

Need help?

MageBooster installs Mage-OS for new stores, moves existing Magento stores to it, and supports stores that already run it, with Hyvä or standalone. We work with stores in Türkiye, Germany, the UK and across Europe, in Turkish, German and English.