Install Light

Light ships as Composer packages on packages.disrex.nl. One metapackage installs the whole admin. This page takes a shop from nothing to Light 0.4, with the commands the install tests ran on Mage-OS 3.5, Magento 2.4.9 and a live Hyvä shop on Magento 2.4.8-p5. Every release since is checked to resolve from packages.disrex.nl on those three platforms.

Every command below is composer … or bin/magento …. On a RollDev environment use roll composer … and roll magento …, which run the same command in the PHP container.

RequirementsCopy Anchor Link

Light needs nothing from the storefront theme, so it installs on any of these shops. Its own dependencies come along: disrex/module-ai from packages.disrex.nl, mollie/magento2 ^3.1.4, paynl/magento2-plugin ^4.0 and dompdf/dompdf from Packagist.

What you installCopy Anchor Link

Packages and compatibility lists every package, which ones install on their own, what a shop may leave off and the bridges to other modules.

Access to packages.disrex.nlCopy Anchor Link

Store the credentials once per machine, in Composer's global auth.json:

composer config --global http-basic.packages.disrex.nl <user> <token>

Leave out --global to write them to the project's auth.json instead. Keep that file out of git.

The repositoryCopy Anchor Link

A shop that doesn't know packages.disrex.nl yet adds it, limited to Light's vendors so it never serves another package:

composer config repositories.disrex '{"type":"composer","url":"https://packages.disrex.nl/","only":["mrx/*","magerex/*","disrex/*"]}'

Use composer config, not a hand edit or jq: a shop's repositories can be a list or an object, and composer config writes either.

A shop that has packages.disrex.nl already (every Disrex shop) keeps its entry and adds an exclude for Mollie and Pay.: packages.disrex.nl holds old copies of both (Mollie 2.49, Pay. 4.0.7) that would hide the current releases on Packagist, and Light's Mollie bridge needs Mollie 3. In composer.json, the entry then reads:

"disrex": {
    "type": "composer",
    "url": "https://packages.disrex.nl/",
    "exclude": ["mollie/*", "paynl/*"]
}

First installCopy Anchor Link

composer require 'magerex/distribution-nl:^0.4'
bin/magento module:enable Mrx_Light Mrx_Ai Mrx_Apps Mrx_Catalog Mrx_Content Mrx_Customers \
    Mrx_Discounts Mrx_Documents Mrx_Home Mrx_Locations Mrx_Orders Mrx_Settings Mrx_Themes \
    Mrx_CountryNl Mrx_PaymentsMollie Mrx_PaymentsPaynl MageRex_Support \
    Disrex_Ai Mollie_Payment Paynl_Payment
bin/magento setup:upgrade
bin/magento cache:flush

Run setup:upgrade straight after composer require, and module:enable before it. Until it has run, the database is behind the code, and Magento's admin stops with its "Please upgrade your database" error.

For a Hyvä shop, require 'magerex/distribution-nl-hyva:^0.4' instead and add Hyva_CompatModuleFallback Mrx_ContentHyva Mrx_DiscountsHyva Mrx_SettingsHyva to the module:enable line: the three Light Hyvä modules need Hyvä's compat-module fallback, which the Hyvä theme module doesn't enable on its own.

• -w: on a shop that already locks some of Light's dependencies at older versions (Mollie 2, for one), add -w to the require so Composer may update those as well; without it the require stops on the conflict. If the shop's own composer.json requires mollie/magento2, require 'mollie/magento2:^3.1.4' in the same command.
• module:enable names every module the metapackage brings, with the three it needs from other vendors (Disrex_Ai, Mollie_Payment, Paynl_Payment): module:enable refuses a module whose required packages' modules are off. Name them all. module:enable writes every module on disk into app/etc/config.php, and one that isn't listed there yet and isn't named goes in as 0, disabled. Without the module:enable step, setup:upgrade enables every module that config.php doesn't list yet, and that is how the install tests ran; it leaves a module that config.php lists as 0 off, which naming it fixes. The admin is white-label: it shows the platform's own logo until you add the MageRex brand.
• setup:upgrade creates Light's tables, runs its data patches and prints the compatibility gate's line: Light API 0.4.0: every module that extends Light is in range. Any other line names the module that is out of range.

In production mode, compile and deploy as for any new module, after setup:upgrade:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

In developer mode, skip the compile: developer mode builds generated code on demand.

Hyvä shopsCopy Anchor Link

The -hyva modules add templates and Tailwind classes to the storefront. Let Hyvä list them, then run your Hyvä theme's Tailwind build:

bin/magento hyva:config:generate

Hyvä code in a -hyva module explains what the build picks up.

Check the installCopy Anchor Link

bin/magento module:status --enabled | grep -cE '^(Mrx|MageRex)_'
bin/magento mrx:light:doctor

The count is 17 for magerex/distribution-nl, 20 for magerex/distribution-nl-hyva, and one more for each add-on: Returns, rate tables, the Flex bridge and the MageRex brand. From 0.2.0 to 0.4.8 it was 18 and 21, with MageRex_Branding in the metapackage.

The doctor, mrx:light:doctor, checks Light and every module that extends it: ranges, pools, routes, layout, the second factor, email templates. It ends with 0 errors, and exits with 1 when it finds one, so a deploy script can stop on it. Findings about modules that don't extend Light show as one summary line and never fail it; --all lists them, and --module=<Vendor_Module> checks one module, a pack or your own bridge (Doctor rules). Run it after the install, after every update, and after you install or update a module that extends Light.

What changes on an existing shopCopy Anchor Link

• The admin. Every admin user works in Light's simple mode by default. "Switch to advanced mode" opens the stock admin, per admin user.
• PDFs. Light's Documents module makes the invoice, credit memo and packing slip PDFs, also from Magento's own print buttons. Modules that plug Magento's PDF classes stop showing their changes; Settings > Emails & documents names them. "Magento classic" (Stores > Configuration > Sales > Emails and documents (Light) > Advanced) gives the stock PDFs and mails back (Plugins on the stock PDF classes).
• Mails. Order, invoice and shipment mails get Light's layout. A template the owner saved in Marketing > Email Templates keeps winning.
• Hyvä storefront. Mrx_SettingsHyva shows the store's welcome text in a bar above the header. It stays hidden while the text is empty or Magento's default.

Stock and locationsCopy Anchor Link

Light reads stock the way the shop keeps it, on Magento's own inventory:

• Without MSI, or with MSI and one source (most shops): simple mode. Every product has one quantity, and Settings > Locations shows the business address as the one location, with "Add location". Nothing on the other screens says location. Local pickup is Light's own carrier at the business address.
• A second location turns on locations mode. The merchant's first "Add location" makes the business address the first location, copies its stock there and keeps every channel selling the same quantities; then stock per location shows on products, the Stock page and the Ship dialog, and pickup at a location runs on Magento's In-Store Pickup. There is no way back to simple mode, so take a database backup before the first "Add location". On a shop above 3,000 products the copy runs in the cron job mrx_locations_conversion, so cron must run.
• Without MSI Mrx_Locations is enabled and does nothing; Settings > Locations stays hidden.

A shop that already keeps stock at several MSI sources opens in locations mode. Locations and pickup explains both modes for module developers.

Two-factor sign-inCopy Anchor Link

Light follows Magento_TwoFactorAuth. While it is on, Light shows nothing of the admin (no menu, no counts, no store name) until the second factor is done, and every light/* request refuses a half-signed-in session. Each role Light makes (the Staff and Shipping staff presets, roles from Light's role editor) holds Magento_TwoFactorAuth::tfa, so staff can set up and use their own second factor. setup:upgrade gives that resource to existing roles that hold Mrx_Light::light, also one made in Magento's own role editor with Light ticked.

A module that switches the second factor off without granting the two-factor session (MarkShust_DisableTwoFactorAuth, WolfSellers_EnableDisableTfa) keeps every Light page on the two-factor screen; the doctor warns with tfa_bypass (Light keeps sending you to the two-factor screen). Keep the second factor on a live shop.

The setup guideCopy Anchor Link

Home shows a setup guide of eight steps until each is done: a first product, business details, a logo, payments, shipping, taxes, a test order and the legal pages. On a shop that already sells, most steps are done at once. What the install tests met:

• Business details is done once no sender address is an example such as owner@example.com. The page flags such a sender.
• Payments counts a method only when its provider is connected, as Settings > Payments shows it. Mollie and Pay. need the shop's own keys.
• Shipping is done once a zone has a rate, or local pickup is on.
• Taxes: the Dutch VAT card on Settings > Taxes sets up 21%, 9% and 0%. A shop that charges Dutch VAT already counts as set up, and the card leaves its rates, rules and classes as they are.
• Test order: place one on the storefront; on a local shop, set up mail first (Mail in a local RollDev shop).

Returns, an add-onCopy Anchor Link

Returns is not part of either metapackage. Add it when the shop takes returns:

composer require 'mrx/module-returns:^0.4'
bin/magento setup:upgrade

It brings mage-os/module-rma from Packagist (Mage-OS 3.x ships it already), which needs Magento_GraphQl and Magento_Webapi; a shop that removed them can't install it, and Adobe Commerce has its own returns module. A shop that disabled packagist.org in its composer.json adds it back for this package. Return mails go out only while "Accept return requests" is on in Settings > Returns.

To take Returns out, disable both modules before you remove the package, then remove it:

bin/magento module:disable Mrx_Returns MageOS_RMA
composer remove mrx/module-returns
bin/magento setup:upgrade

Dump the database first. A setup:upgrade that runs while the modules are disabled and their code is still installed drops the rma_* tables, returns included. Once the code is gone, setup:upgrade leaves the tables and the returns in them alone. Removing the package without disabling the modules first leaves every bin/magento command failing until the cache storage is cleared (Updating).

Rate tables, an add-onCopy Anchor Link

Light's shipping zones set a price per group of countries, by weight, free above an amount. For prices by region or postcode, or in steps by order amount or number of items, add the rate table pack. It is in neither metapackage:

composer require 'mrx/module-shipping-matrixrate:^0.4'
bin/magento module:enable WebShopApps_MatrixRate Mrx_ShippingMatrixrate
bin/magento setup:upgrade
bin/magento cache:flush

It brings webshopapps/module-matrixrate 20.5 (MatrixRate) from Packagist; packages.disrex.nl holds no copy of it, so the repository entry needs no exclude for it. A shop that disabled packagist.org in its composer.json adds it back for this package. Settings > Shipping and pickup then asks "How do you charge shipping?", per channel: Shipping zones or Rate table. The zones stay stored while the rate table charges. bin/magento mrx:light:doctor --module=Mrx_ShippingMatrixrate prints "No problems found." The pack's README has the rest.

Flex shops, an add-onCopy Anchor Link

A shop that runs Disrex Flex (Disrex_FlexCore, Hyvä only) adds the Flex bridge. It is in neither metapackage:

composer require 'magerex/module-flex-bridge:^0.4'
bin/magento module:enable MageRex_FlexBridge
bin/magento setup:upgrade
bin/magento cache:flush

Light's Home, Content > Pages, the page editor and the category and product editors then open the Flex Editor in a new tab. Without FlexCore the package shows nothing and its URLs answer 404. A custom role that held Content before the install has no rule for the editor: open it in Settings > Users and permissions and save it once. The package's README has the rest, such as which store view opens.

The MageRex brand, an add-onCopy Anchor Link

A metapackage install shows the platform's own logo and theme: Mage-OS on Mage-OS, Magento on Magento Open Source. For the MageRex logo, favicon, sign-in page and the Baken default theme, add the brand package. It is in neither metapackage:

composer require 'magerex/light-branding:^0.4'
bin/magento module:enable MageRex_Branding
bin/magento setup:upgrade
bin/magento cache:flush

A theme an admin picked, and a store default someone saved, stay as they are; the brand sets the default only where none was saved. An own logo uploaded in Settings beats the brand's. To take the brand out, composer remove magerex/light-branding and run setup:upgrade: it keeps no data, and the admin shows the platform's brand again. A branding package shows how to make one for your own agency.

UpdatingCopy Anchor Link

composer update 'mrx/*' 'magerex/*' -w
bin/magento setup:upgrade
bin/magento cache:flush

-w updates the Light packages and the packages they need, and leaves the packages your shop requires itself, such as its own payment plugin, at their locked versions. When Composer says a package your shop requires is in the way, use -W, which updates those too; check what it changed before you deploy.

composer update stays inside the range in the shop's composer.json. That is enough for a patch (0.4.0 to 0.4.1), but a shop that required ^0.3 never reaches 0.4.0 that way: a caret on 0.x stops at the next minor. Move the range with a require, for every Light package the shop requires itself:

composer require 'magerex/distribution-nl:^0.4' -w
bin/magento setup:upgrade
bin/magento cache:flush

Add 'mrx/module-returns:^0.4' and 'mrx/module-shipping-matrixrate:^0.4' to the same require when the shop has them, and use magerex/distribution-nl-hyva on a Hyvä shop. From 0.1.x, setup:upgrade creates mrx_location, mrx_location_stock and mrx_order_pickup and enables Mrx_Locations, which comes in with the update. A module of your own that extends Light moves its ranges too (Upgrading from 0.3.x to 0.4.0). Run setup:upgrade right after composer: between the two the admin is unusable. Composer has put the new code next to a database that doesn't know it, and a module that comes in with the update, such as Mrx_Locations from 0.2, is still off. Light's Home then fails with "Cannot instantiate interface Mrx\Locations\Api\LocationsInterface" until setup:upgrade enables it.

After the update, run bin/magento mrx:light:doctor: it names a module whose Light range no longer matches.

In production mode, run setup:di:compile and setup:static-content:deploy after setup:upgrade, as on the first install. Run setup:upgrade on every update, even a patch: 0.1.2 adds four database indexes for the orders, customers and Home screens, and only setup:upgrade creates them. On a large shop that first run takes longer while MySQL builds them. Changelog lists what each release changed.

Mail in a local RollDev shopCopy Anchor Link

A new RollDev shop on Mage-OS 3.5 or Magento 2.4.9 sends no mail: the PHP image's sendmail command is one that the Symfony mailer refuses ("Unsupported sendmail command flags"), so an order confirmation fails with "Unable to send mail" while the order itself goes through. Send mail over SMTP to RollDev's mail catcher instead:

bin/magento config:set system/smtp/transport smtp
bin/magento config:set system/smtp/host mailhog
bin/magento config:set system/smtp/port 1025

Mail then lands in https://mailhog.roll.test/. This is for a local shop only.

TroubleshootingCopy Anchor Link

• Every Light module is disabled after the first setup:upgrade. It ran with --keep-generated on 0.1.1 or earlier. Enable them again (bin/magento module:enable with the names from app/etc/config.php, or put that file back) and run setup:upgrade without the flag.
• The doctor reports findings. Doctor rules explains each rule and its fix.
• Light pages keep sending you to the two-factor screen. A module skips the second factor without granting it (Light keeps sending you to the two-factor screen).
• A module's Light parts are gone, or a red banner names a module. Its Light API range doesn't match (A module's Light parts are gone).
• A Hyvä storefront part doesn't show. Run hyva:config:generate and the Tailwind build again (A storefront change of a -hyva module doesn't show).
• Composer stops on another repository with HTTP 401. A private repository of the shop, such as Hyvä's Private Packagist, needs its own credentials in auth.json; that isn't Light's.
• A product save logs OpenSearch 403 errors on a new local shop. OpenSearch blocks index creation when the Docker disk is nearly full. Free disk space, then run bin/magento indexer:reindex.
• Anything else: Troubleshooting.