Magento Multi-Store Setup Guide

What "multi-store" actually means

Magento can run several independent storefronts — different brands, domains, even catalogues — from a single codebase and database. The piece that trips people up is the hierarchy. Get these three levels straight and the rest is mechanical:

Why most tutorials are wrong: scopes live in the database

Older guides tell you to edit app/etc/config.php or env.php to add stores. On current Magento that's incorrect — websites, stores and store views are database records, created in the admin (or programmatically). config.php only records which modules are enabled. If a tutorial has you hand-editing config files to add a website, it predates 2.4 and will lead you astray.

Step-by-step admin setup

All four steps live under Stores → Settings → All Stores.

1. Create the website

• Create Website. Give it a Name and a Code — lowercase, no spaces, no leading digit (e.g. brand_a). Remember this code: it goes into your web-server config verbatim.

2. Create the store (group)

• Create Store. Choose the website, give it a Name, a Code, and a Root Category.

Magento\Framework\Validator\Exception:
Invalid type given. String, integer or float expected

3. Create the store view

• Create Store View. Choose the store, give it a Name, a Code, set Status = Enabled. The view is what carries language, theme and URLs.

4. Set per-website base URLs

• Go to Stores → Configuration, switch the scope selector (top-left) to the target website, then Web → Base URLs (and Base URLs (Secure)).
• Untick "Use Default Value" and set the secure base URL to that brand's domain, e.g. https://brand-a.example/.

5. Assign a theme per store view

• Content → Design → Configuration, edit the target store view's row, set its theme. Themes are assigned per store view, so each brand can look completely different.

Wiring your web server (nginx)

The web server has to tell Magento which website a request belongs to, using the MAGE_RUN_CODE variable. Map each hostname to its website code:

map $http_host $MAGE_RUN_CODE {
    default                  "";
    brand-a.example          "brand_a";
    www.brand-a.example      "brand_a";
    brand-b.example          "brand_b";
    www.brand-b.example      "brand_b";
}
map $http_host $MAGE_RUN_TYPE {
    default "website";
}

Then — and this is the part guides omit — the two variables must be forwarded to PHP in the location block that runs index.php / static.php:

location ~ ^/(index|get|static|errors/report|health_check)\.php$ {
    fastcgi_param MAGE_RUN_CODE $MAGE_RUN_CODE;   # required
    fastcgi_param MAGE_RUN_TYPE $MAGE_RUN_TYPE;   # required
    # ...your usual fastcgi_pass + params...
}

Validate and reload: nginx -t && nginx -s reload. The host on the left of the map must match the website code on the right exactly.

DNS, SSL & testing before cutover

• Each brand domain needs its own TLS certificate. Issue one per domain (e.g. via Let's Encrypt) before going live.
• Test a domain before you point its DNS, by resolving it to your server manually:

  curl -sk --resolve brand-a.example:443:YOUR.SERVER.IP \
       -o /dev/null -w "%{http_code}\n" https://brand-a.example/

  A 200 or 302 means the store resolves correctly. A 500 usually means a website-code mismatch — check the exception log.

Common failures & fixes

Go-live checklist

• Website, store group (with code!), and store view created for each brand.
• Per-website secure base URLs set, with the scope selector switched correctly.
• Theme assigned per store view.
• nginx host → MAGE_RUN_CODE map complete (apex and www), and the two fastcgi_param lines present.
• A TLS certificate issued per domain.
• Each domain tested with --resolve and returning 200/302 before DNS cutover.
• bin/magento cache:flush and indexer:reindex run; static content deployed for all locales.