Installation

Composer enforces the extension list when it resolves the project, and composer check-platform-reqs reports it at any time. In the Mage-OS 3.6.0 project the command printed success for every line:

Source: Adobe: PHP settings

Adobe’s list for the Adobe-hosted packages also names ext-ftp, which the Mage-OS project does not require, and the Docker image used here compiled the other extensions (bcmath gd intl pdo_mysql soap sockets xsl zip sodium pcntl) with docker-php-ext-install. Two optional extensions are worth adding: pcntl, which the indexers need to run in parallel mode, and igbinary, which the installer writes as the cache serialiser ("serializer": "igbinary"), as the installer help says it is 70 percent faster and 58 percent smaller than PHP serialisation. A container without igbinary still served pages in the first test, and the stack built later with the extension installed worked the same way, so install it when you want the smaller, faster cache entries.

The documented php.ini settings are short:

The same settings must reach both the command-line PHP and the web server’s PHP (php.ini for Apache’s module, the FPM pool file and the PHP command line’s own ini). Adobe "strongly recommends" the same values in both, because the install and upgrade run in the CLI and the store runs in the web SAPI. In Debian-style systems these are different directories (/etc/php/8.5/cli, /etc/php/8.5/fpm).

Source: Adobe: PHP settings

Create an empty database with its own user. The installer creates the tables, so the account needs full rights on that schema only.

Source: Adobe: Configure the database server

Replace % with the host the web server connects from. Adobe’s database page adds four requirements that you must handle yourself. Magento creates database triggers when an indexer runs in Update by Schedule mode, so the account needs the right to create triggers (ALL PRIVILEGES includes it). Enable the STRICT_ALL_TABLES SQL mode on a new project. Use only row-based replication, because statement-based replication is not supported and CREATE TEMPORARY TABLE inside transactions breaks GTID-based replication on some managed services. And raise max_allowed_packet above its 16 MB default if you import large catalogues. The installer itself rejects a wrong password early:

2.4.9 uses OpenSearch 3 (2.x still works). The Mage-OS 3.6.0 installer still accepts --search-engine=elasticsearch8, although Adobe’s 2.4.9 table lists only OpenSearch. The installer stops when it cannot reach the search engine (see the errors table), because the storefront catalogue, layered navigation and search all read from it. A single node is enough for a laptop or a small shop:

Source: Adobe: Search engine overview

On 2026-10-27 the last command answered with the version block ("number": "3.9.0", "distribution": "opensearch"). The security plugin is disabled in this example because the container is reachable only from its Docker network; on a shared network keep it on and give the installer --opensearch-enable-auth=1 --opensearch-username=<user> --opensearch-password=<password>. Give every store sharing a cluster its own index prefix with --opensearch-index-prefix: an index is named <prefix>_product_<store view id>_v<version>, so the installs with prefixes magento2 and pocketcoffee never touch each other.

Valkey 9 is the tested key-value store for 2.4.9. It is protocol-compatible with Redis 7.2 and the PHP side still talks to it with Redis commands, which is why some option names still say redis. Magento uses three databases of one server: database 0 for the cache, 1 for the full-page cache and 2 for sessions, "to protect against data loss" when you flush one of them.

Source: Adobe: Valkey for the cache

The server reports redis_version:7.2.4 (the compatibility version) and valkey_version:9.1.3. Details of the Magento side, including a trap in the session options, are in the Valkey section below.

Without a broker Magento falls back to a MySQL queue (tables queue, queue_message, queue_message_status), which is acceptable for a small shop. Consumers process asynchronous operations such as REST bulk and asynchronous endpoints and Inventory mass actions; a broker is the scalable transport for them. Adobe lists RabbitMQ 4.3 and ActiveMQ Artemis 2 for 2.4.9; the release notes call Artemis the long-term replacement for RabbitMQ. The test used the public rabbitmq:4 image, which resolved to RabbitMQ 4.4.0 on 2026-10-27, newer than the version in Adobe’s table, and everything worked:

Source: Adobe: Install and configure RabbitMQ

repo.magento.com requires authentication for every package, open source ones included. In the Commerce Marketplace open My Profile, choose Access Keys in the Marketplace tab and select Create a New Access Key. You get two 32-character strings: the public key is the Composer username and the private key is the password. Since August 2022 the account owner needs an Adobe ID linked to the Commerce account before keys can be generated, and keys carry the entitlement of the account (the Primary Contact’s MAGEID), which is why a developer may see no Access Keys section until the account owner grants access or an invoice is settled. You can disable, re-enable or delete keys, for example when a contractor leaves; key one pair per person and per CI system so one can be revoked alone.

Composer reads credentials from a global auth.json, a project auth.json or the COMPOSER_AUTH environment variable, so you are not prompted each time. The project ships auth.json.sample; a real auth.json must never be committed.

Source: Adobe: Get your authentication keys

With placeholder values, the first command wrote an auth.json whose http-basic object had the key repo.magento.com with username and password, and composer config -g --list printed [http-basic.repo.magento.com.username] for the second form. No request to repo.magento.com was made. Mage-OS’s repository needs none of this.

setup:install --help of Mage-OS 3.6.0 lists about 180 options. These are the ones that matter, grouped by what they configure. Defaults are from the help output.

Mage-OS adds a helper: a setup:install run that fails parameter validation starts with the line Tip: Run bin/magento install for a guided interactive installation. The command install ("Interactive Mage-OS installation wizard", registered in the list output) asks the same questions in stages (environment, database, admin, store, backend, document root, search engine, Redis or Valkey, RabbitMQ, logging, sample data and theme), detects services it can reach, checks permissions and runs setup:install for you; with -vvv it prints the underlying command. It needs a terminal, so it was listed and read but not driven here.

Source: Adobe: Install the application from the command line

An excerpt of the generated env.php (without the crypt key, the database password and the GraphQL salt, which are secrets and must never be pasted anywhere or committed with a public repository):

Source: Adobe: env.php reference

Three observations from the run. The installer wrote MAGE_MODE as default and left cache types enabled (16 types). downloadable_domains was set from the base URL (localhost); a store behind another domain must add that domain here or with bin/magento downloadable:domains:add (and downloadable:domains:show lists them). All 11 indexers finished Ready with Update On: Schedule, which means index changes are queued by database triggers and applied by cron: with cron not running, a product edit does not reach search or the category pages (see Cron).

Verification after the install, with their 2026-10-27 results in the Docker stack:

Source: Adobe: Install the application from the command line

Installing over an installed database is accepted and rerun end to end; in the test it reused the existing Admin URI and finished with [SUCCESS]: Magento installation complete. Use --cleanup-database only when you mean to drop every table: in one test a failed run that included it had already emptied the database when it stopped at the search-engine check, and the store answered HTTP 500 afterwards.

The test image used php:8.5-apache with PHP as an Apache module (mod_php). It needs mod_rewrite, mod_headers and mod_expires, a virtual host whose DocumentRoot is pub/ and AllowOverride All so the shipped .htaccess files (pub/.htaccess, pub/static/.htaccess, pub/media/.htaccess) take effect.

Source: Adobe: Apache

apachectl -M listed rewrite_module, headers_module, expires_module and deflate_module in the test image. For anything beyond a laptop put PHP-FPM behind Apache (proxy_fcgi) instead of mod_php, so web workers and PHP workers can be sized separately; that variant was not run here. The shipped .htaccess also carries a commented SetEnv MAGE_MODE line for choosing the mode from the server configuration.

Nginx is the web server that the shipped sample configuration targets. The project root contains nginx.conf.sample, a complete set of location blocks (255 lines in 3.6.0): the PHP entry points index.php, get.php, static.php, health_check.php and the error pages, the /static/ rewrite that strips the version123456 segment, long cache headers, denial of /media/customer/, /media/downloadable/, /media/import/, /media/custom_options/ and /media/customer_address/, the setup and update entry points (denied unless you open them), a gzip block and a final deny rule for .php, .phtml, .htaccess, .htpasswd and .git anywhere else. You include it from your own server block:

Source: Adobe: Nginx

nginx -t with this file, with the sample copied next to it and the upstream pointing at 127.0.0.1:9000, answered the configuration file /etc/nginx/nginx.conf syntax is ok and configuration file /etc/nginx/nginx.conf test is successful on nginx/1.30.6. No PHP-FPM pool was attached, so request handling through Nginx was not exercised. Two points need your attention. The line add_header Cache-Control "public, max-age=31536000, immutable" in the /static/ block is commented out in the sample and should be enabled in production mode only (static URLs carry the version segment, so a change in content changes the URL). And set $MAGE_MODE production only has an effect when you also pass fastcgi_param MAGE_MODE $MAGE_MODE; in the PHP location blocks; the CLI-written env.php value is the safer source.

A PHP-FPM pool for a small store. Size pm.max_children by memory, not by guesswork: measure the resident size of a worker under realistic load and divide the memory you can spare by it.

Source: Adobe: PHP settings

The pool is a recipe assembled from Adobe’s PHP settings and the Nginx sample’s PHP_VALUE memory_limit=756M; it was not run in this test. pm.max_requests recycles workers to bound memory growth, and request_terminate_timeout should be at least the fastcgi_read_timeout of 600 s that the sample sets.

Terminate TLS at the web server, a load balancer or a CDN, and tell Magento about it:

Source: Adobe: Set configuration values

Six of the seven commands were run (all but the unsecure base URL) and each answered Value was saved. With use_in_adminhtml on, a plain HTTP request to the Admin path returned 302 to an https URL, and a request carrying X-Forwarded-Proto: https was accepted with 200, which is what offloader_header is for: a TLS-terminating proxy that talks plain HTTP to PHP must announce the original scheme, or Magento treats the request as plain HTTP. HSTS and upgrade-insecure-requests should be switched on only when HTTPS works everywhere, because browsers remember HSTS. The install options --use-secure and --base-url-secure are deprecated for the same reason as the other URL options.

Magento’s full-page cache has two backends: the built-in one (Valkey or files) and Varnish. Varnish is faster for anonymous traffic and is the production recommendation. Set the application to Varnish, generate the VCL and give the purge hosts:

Source: Adobe: Configure Varnish

On Mage-OS 3.6.0 the command is provided by the bundled elgentos/magento2-varnish-extended 2.0.7 module, whose options are --access-list, --backend-host, --backend-port, --export-version (default 6), --grace-period (default 300), --input-file, --output-file and --enable-bfcache. With only the defaults it failed on a fresh install (explode(): Argument #2 ($string) must be of type string, null given from the access-list reader); passing the values explicitly produced a 10,523-byte VCL starting vcl 4.1;, with import cookie; and import std;, a backend default with a /health_check.php probe and a ban(...) on X-Magento-Tags. The official varnish:stable container could not compile it because the cookie VMOD is not in that image, so the VCL was generated and read but not run through Varnish. Install varnish-modules (or the distribution’s package that contains libvmod_cookie) before trying it, and test with varnishd -C -f default.vcl.

A CDN in front of pub/static and pub/media is a configuration change, not a code change: set the Base URL for Static View Files and Base URL for User Media Files under Stores > Configuration > General > Web (the paths web/unsecure/base_static_url, web/unsecure/base_media_url and their secure twins), keep the version123 segment in the static URL so the CDN can use year-long cache headers. HTTP/2 is a web server feature (listen 443 ssl; http2 on; in Nginx 1.25.1 and later), and it reduces the benefit of bundling and merging files; Magento’s built-in bundling and merging are off by default, keep them off unless you have measured a gain, and they are disabled for Hyvä store views, as Hyvä’s documentation advises (see Frontend: Hyvä, PWA Studio and Edge Delivery). For images, catalog:images:resize pregenerates product image sizes after a bulk import, and the sample’s commented image_filter block shows how Nginx can resize catalogue images instead of PHP when its image-filter module is loaded. These items are summarised from the Adobe pages and the configuration sample; none of them was run here.

The tool is a Composer package whose version must match the Magento 2 version:

Source: Adobe: Install the Data Migration Tool

Configuration lives under vendor/magento/data-migration-tool/etc/opensource-to-opensource, opensource-to-commerce and commerce-to-commerce, with one subfolder per supported version. Adobe recommends keeping your copy in a module so it is under source control, with Magento_DataMigrationTool in the module’s sequence. Copy config.xml.dist to config.xml and set the two databases and the encryption key:

Source: Adobe: Configure the Data Migration Tool

crypt_key must be filled: it is the value of the <key> element in app/etc/local.xml of Magento 1, needed to re-encrypt stored values. The optional password, port and <source_prefix>, <dest_prefix> handle non-default connections and table prefixes, and TLS attributes can be added to the database element. direct_document_copy is Adobe’s performance tip, and it requires both databases on the same MySQL server with an account that can read both.

Source: Adobe: Run the Data Migration Tool

--auto keeps going when an integrity check fails; --reset starts again from the beginning (restore the Magento 2 database dump first). The tool saves its progress and resumes from the last good state. The data mode adds tables named m2_cl_<table> and INSERT, UPDATE, DELETE triggers to the Magento 1 database so the delta mode can find what changed; the delta mode then runs continuously, restarting every 5 seconds, until you stop it with Ctrl-C. The delta mode covers customer and order activity from the storefront and Admin operations on orders, products and categories; it does not carry attributes or CMS pages created in the Magento 1 Admin after the data run, and data from extension tables needs an extra deltalog.xml entry and a delta class that extends Migration\App\Step\AbstractDelta.

Adobe’s benchmark on a 2.5 GB, single-core virtual machine with 177,000 products, 355,000 orders and 214,000 customers took about 10 minutes for settings and about 9 hours for data (all data except URL rewrites), with a downtime of "a few minutes to reindex and change DNS" afterwards.

After you have tested the new store thoroughly: put Magento 1 into maintenance mode and stop all Admin activity, let the delta catch up, start the Magento 2 cron jobs, run bin/magento cache:flush and bin/magento indexer:reindex, and change DNS and the load balancer to the Magento 2 servers. Plan for a cold full-page cache. Keep redirects from the old URLs when the URL structure changes (see Admin and Store Setup for URL rewrites).

The Data Migration Tool was not run for these pages, because it needs a Magento 1 database and the tool package from repo.magento.com or a GitHub tag that matches the Magento 2 codebase. The commands, options and behaviour above are from Adobe’s documentation, last updated 2026-10-08, and from the repository’s tags.