Cloud 7.05

Multisite Configuration

Understanding routes.yaml, .magento.app.yaml, magento-vars.php, MAGE_RUN_CODE, and multisite setup.

Exam Critical: Understanding multisite configuration with routes, .magento.app.yaml, and magento-vars.php is important for the exam!

Multisite Configuration

mindmap root((Multisite Setup)) Routes yaml Subdomain routing Wildcard support Upstream config magento app yaml web locations Subfolder config name node magento vars php Runs before index php Access SERVER vars Set MAGE_RUN_CODE Set MAGE_RUN_TYPE Magento Stores Create websites config dump Sync data

Multisite Configuration Overview

Three Key Configuration Files

.magento/routes.yaml

Routes subdomains to Magento application

.magento.app.yaml

Configures web/locations for subfolder sites

magento-vars.php

Sets MAGE_RUN_CODE and MAGE_RUN_TYPE

Routes Configuration (.magento/routes.yaml)

Setting Up Subdomain Routing

Purpose

If you intend to set up Magento stores with subdomains, you need to route these back into the main Cloud backend.

This happens in .magento/routes.yaml.

Wildcard Subdomain Configuration

.magento/routes.yaml
# Using wildcard (*) for any subdomain
"http://*.{default}/":
    type: upstream
    upstream: "mymagento:php"

"https://*.{default}/":
    type: upstream
    upstream: "mymagento:php"
What This Does:
  • Routes any subdomain to Magento application
  • b2b.example.com → Magento
  • b2c.example.com → Magento
  • wholesale.example.com → Magento
  • All subdomains handled by same Magento instance

Hardcoded Subdomain Configuration

# Hardcoding specific subdomains
"http://b2b.{default}/":
    type: upstream
    upstream: "mymagento:php"

"http://b2c.{default}/":
    type: upstream
    upstream: "mymagento:php"

"https://b2b.{default}/":
    type: upstream
    upstream: "mymagento:php"

"https://b2c.{default}/":
    type: upstream
    upstream: "mymagento:php"
Upstream Reference

Note that mymagento is specified in .magento.app.yaml in the name node.

# .magento.app.yaml
name: mymagento
type: php:8.2

.magento.app.yaml Configuration

Subfolder Sites Configuration

Purpose

To configure Magento to serve different sites as a subfolder, you need to update the web/locations configuration in .magento.app.yaml.

Example: /b2b Subfolder Configuration

.magento.app.yaml
web:
    locations:
        "/":
            root: "pub"
            passthru: "/index.php"
            index:
                - index.php
            scripts: true
            allow: false
            rules:
                \.(css|js|map|hbs|gif|jpe?g|png|tiff|wbmp|ico|jng|bmp|svgz|midi?|mp?ga|mp2|mp3|m4a|ra|weba|3gpp?|mp4|mpe?g|mpe|ogv|mov|webm|flv|mng|asx|asf|wmv|avi|ogx|swf|jar|ttf|eot|woff|otf|html?)$:
                    allow: true
                ^/sitemap(.*)\.xml$:
                    passthru: "/media/sitemap$1.xml"
        "/media":
            root: "pub/media"
            allow: true
            scripts: false
            passthru: "/get.php"
        "/static":
            root: "pub/static"
            allow: true
            scripts: false
            passthru: "/front-static.php"
            rules:
                ^/static/version\d+/(?.*)$:
                    passthru: "/static/$resource"
        
        # B2B subfolder configuration
        "/b2b":
            root: "pub"
            passthru: "/index.php"
            index:
                - index.php
            scripts: true
            allow: false

magento-vars.php - The Powerful Router

Understanding magento-vars.php

Power of magento-vars.php

This is a powerful file that is run before pub/index.php.

Capabilities:
  • Configure most (all?) server, post, and get variables going into Magento
  • Saves you from modifying pub/index.php
  • No need to maintain modifications through composer updates
  • Has access to everything in $_SERVER superglobal
  • Can access environment variables

File Location

magento-vars.php

Place this file in the root directory (same level as pub/, app/, etc.)

$_SERVER Variables Available

Environment Variables in magento-vars.php

Example URL

http://staging-55555-vvvvvvv.us-4.magentosite.cloud/b2b/
Available $_SERVER Variables:
Variable Example Value Description
MAGENTO_CLOUD_APPLICATION Base64-encoded JSON Base64-encoded version of .magento.app.yaml
MAGENTO_CLOUD_ROUTES Base64-encoded JSON Base64-encoded version of all routes
HTTP_HOST staging-55555-vvvvvvv.us-4.magentosite.cloud Hostname of the request
HTTP_X_ORIGINAL_ROUTE http://{default}/ Original route template
DOCUMENT_URI /b2b/index.php Current document URI
DOCUMENT_ROOT app/pub/ Document root directory

magento-vars.php Routing Example

Setting MAGE_RUN_CODE and MAGE_RUN_TYPE

Basic B2B Routing Example

magento-vars.php
<?php
// magento-vars.php
if (isset($_SERVER['DOCUMENT_URI']) && 
    stripos($_SERVER['DOCUMENT_URI'], '/b2b/') !== false) {
    $_SERVER["MAGE_RUN_CODE"] = "b2b";
    $_SERVER["MAGE_RUN_TYPE"] = "website";
}
What This Does:
  • Checks if URL contains /b2b/
  • Sets MAGE_RUN_CODE to "b2b" (website code)
  • Sets MAGE_RUN_TYPE to "website"
  • Magento loads the B2B website configuration

Advanced Subdomain Routing

<?php
// magento-vars.php
// Route based on subdomain
if (isset($_SERVER['HTTP_HOST'])) {
    $host = $_SERVER['HTTP_HOST'];
    
    // B2B subdomain
    if (strpos($host, 'b2b.') === 0) {
        $_SERVER["MAGE_RUN_CODE"] = "b2b";
        $_SERVER["MAGE_RUN_TYPE"] = "website";
    }
    
    // B2C subdomain
    if (strpos($host, 'b2c.') === 0) {
        $_SERVER["MAGE_RUN_CODE"] = "b2c";
        $_SERVER["MAGE_RUN_TYPE"] = "website";
    }
    
    // Wholesale store
    if (strpos($host, 'wholesale.') === 0) {
        $_SERVER["MAGE_RUN_CODE"] = "wholesale";
        $_SERVER["MAGE_RUN_TYPE"] = "store";
    }
}

Debugging: Print $_SERVER Variables

<?php
// magento-vars.php
// Use this to understand available variables
print_r($_SERVER);
exit;

Debugging Only!

Remove print_r($_SERVER) after debugging! Never leave this in production.

Complete Multisite Setup Workflow

Step-by-Step Implementation

Step 1: Create Websites in Magento Admin

  1. Navigate to Stores → All Stores
  2. Click Create Website
  3. Enter website details:
    • Name: B2B
    • Code: b2b
  4. Create store and store view under website
  5. Configure website settings

Step 2: Dump Configuration

./vendor/bin/ece-tools config:dump

This exports website/store configuration to app/etc/config.php

Step 3: Configure Routes (.magento/routes.yaml)

"http://b2b.{default}/":
    type: upstream
    upstream: "mymagento:php"

"https://b2b.{default}/":
    type: upstream
    upstream: "mymagento:php"

Step 4: Configure magento-vars.php

<?php
if (isset($_SERVER['HTTP_HOST'])) {
    $host = $_SERVER['HTTP_HOST'];
    
    if (strpos($host, 'b2b.') === 0) {
        $_SERVER["MAGE_RUN_CODE"] = "b2b";
        $_SERVER["MAGE_RUN_TYPE"] = "website";
    }
}

Step 5: Commit and Deploy

git add .magento/routes.yaml magento-vars.php app/etc/config.php
git commit -m "Add B2B multisite configuration"
git push origin integration

Step 6: Sync Data Across Environments

Important: Don't forget updating app/etc/config.php in production and then syncing data back to staging and integration.

  1. Create stores in production admin
  2. Run config:dump in production
  3. Pull config.php from production to staging/integration
  4. Or: Sync database from production to lower environments

MAGE_RUN_CODE and MAGE_RUN_TYPE

Understanding Run Parameters

Parameter Purpose Values
MAGE_RUN_CODE Code of website or store to load Website code (e.g., "b2b", "b2c") or Store code
MAGE_RUN_TYPE Type of entity to load "website" or "store"

Examples

// Load B2B website
$_SERVER["MAGE_RUN_CODE"] = "b2b";
$_SERVER["MAGE_RUN_TYPE"] = "website";

// Load specific store
$_SERVER["MAGE_RUN_CODE"] = "german_store";
$_SERVER["MAGE_RUN_TYPE"] = "store";

Practical Experience Tips

Hands-On Learning

Recommended Exercises

  • Configure multiple stores: Create at least 2 websites in admin
  • Use print_r($_SERVER): In magento-vars.php to understand available variables
  • Configure /b2b URL path: Set up subfolder routing
  • Test subdomain routing: Configure b2b.domain.com
  • Sync config.php: Practice syncing between environments

Common Configurations

Popular Multisite Patterns

Pattern 1: Subdomain per Website

URLs:
  • b2b.example.com
  • b2c.example.com
  • wholesale.example.com
Configuration:
  • Wildcard route in routes.yaml
  • HTTP_HOST detection in magento-vars.php
  • MAGE_RUN_TYPE = "website"

Pattern 2: Subfolder per Website

URLs:
  • example.com/b2b/
  • example.com/b2c/
  • example.com/wholesale/
Configuration:
  • web/locations in .magento.app.yaml
  • DOCUMENT_URI detection in magento-vars.php
  • MAGE_RUN_TYPE = "website"

Pattern 3: Different Domains

URLs:
  • b2bstore.com
  • b2cstore.com
Configuration:
  • Hardcoded routes in routes.yaml
  • HTTP_HOST detection in magento-vars.php
  • DNS pointing to Cloud environment

Troubleshooting

Common Issues

Issue 1: Subdomain Not Routing

Solution:
  1. Verify routes.yaml has subdomain configured
  2. Check upstream name matches .magento.app.yaml
  3. Redeploy after routes.yaml changes
  4. Check DNS points to Cloud environment

Issue 2: Wrong Website Loading

Solution:
  1. Debug: Add print_r($_SERVER) in magento-vars.php
  2. Verify MAGE_RUN_CODE matches website code in admin
  3. Check if condition in magento-vars.php is correct
  4. Clear cache: bin/magento cache:flush

Exam Tips

Key Points to Remember

  • Routes file: .magento/routes.yaml for subdomain routing
  • Wildcard: Use * for any subdomain
  • Upstream: Must match name node in .magento.app.yaml
  • Subfolder config: Update web/locations in .magento.app.yaml
  • magento-vars.php: Runs BEFORE pub/index.php
  • $_SERVER access: magento-vars.php has full $_SERVER access
  • MAGE_RUN_CODE: Website or store code
  • MAGE_RUN_TYPE: "website" or "store"
  • Key variables: HTTP_HOST, DOCUMENT_URI, MAGENTO_CLOUD_ROUTES
  • Config sync: Update config.php in production, sync to lower environments
  • Debugging: Use print_r($_SERVER) to see available variables
Previous: Cloud 7.04 Enable/Disable Module Practice Cloud 7.05