MODX Contexts for Multisite: Step-by-Step Guide

MODX Contexts for Multisite Setup

You need to run three sites—Russian, English, and Belarusian—each with its own domain, templates, and content. Usually that means three MODX installations: triple updates, backups, and configurations. MODX contexts solve this problem: one engine, multiple sites. Setup takes 2–3 days instead of a week for three separate installations. According to MODX documentation, contexts provide full isolation without core duplication. Our engineers with 5+ years of experience ensure a stable multisite structure. Over 50 successful projects on MODX. Average support cost savings of 30%, hosting savings up to 40%.

What Are Contexts and Why Do You Need Them?

Contexts are isolated environments within a single MODX installation. Each context has its own settings, root resources, templates, and even language parameters. Compare with other approaches:

Context setup is 3 times faster than deploying separate installations. Hosting savings up to 40%, support costs cut by 30% on average across our projects. Plus, you get a single entry point for management: MODX updates, plugins, and components are centrally managed.

How to Set Up Contexts: Step-by-Step Guide

Create and Configure a Context

System → Contexts → Create → key en (short Latin only). After creation, configure parameters:

Key: en
Name: English
Version Settings:
  base_url: /en/
  site_url: https://yourdomain.com/en/
  site_start: 55 (root resource ID)
  error_page: 56
  default_template: 3
  cultureKey: en
  locale: en_US.UTF-8

Automatic Domain-Based Switching

Plugin on the OnHandleRequest event switches context based on HTTP_HOST or URI:

$host = $_SERVER['HTTP_HOST'];
$uri = $_SERVER['REQUEST_URI'];
$contextMap = [
    'ru.company.com' => 'ru',
    'en.company.com' => 'en',
    'by.company.com' => 'by',
];
if (isset($contextMap[$host])) {
    $contextKey = $contextMap[$host];
    if ($modx->context->key !== $contextKey) {
        $modx->switchContext($contextKey);
    }
    return;
}
$prefixMap = ['/ru/' => 'ru', '/en/' => 'en', '/uk/' => 'uk'];
foreach ($prefixMap as $prefix => $contextKey) {
    if (strpos($uri, $prefix) === 0) {
        if ($modx->context->key !== $contextKey) {
            $modx->switchContext($contextKey);
        }
        return;
    }
}

Nginx Configuration for Subdomains

server {
    listen 443 ssl http2;
    server_name ru.company.com en.company.com by.company.com;
    root /var/www/company.com;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_HOST $host;
        include fastcgi_params;
    }
}

Resources and Cross-Context Links

Each resource is tied to a context via the context_key field. To create a resource in context en:

$resource = $modx->newObject('modDocument');
$resource->set('pagetitle', 'About Us');
$resource->set('alias', 'about-us');
$resource->set('context_key', 'en');
$resource->set('template', 3);
$resource->set('parent', 55);
$resource->save();

For cross-context links, specify the context: [[~42? &context=en]].

Settings Synchronization

System settings have priority: Global > Context > Namespace. Context settings override global ones. Example of getting the URL for the current context:

$siteUrl = $modx->getOption('site_url'); 

Why Contexts Beat Separate Installations?

• Resource saving: single database, single core.
• Unified admin panel: manage all sites from one interface.
• Quick deployment: a new context can be set up in an hour.
• Easy updates: update MODX once.

See for yourself: contact us for a consultation. Our engineers with 5+ years of experience can assess your project. Get an accurate estimate and implementation plan.

What Typical Mistake Happen During Context Setup?

Even experienced developers make a few slips. The most common is incorrectly linking the root resource site_start. If the resource doesn't belong to the context, MODX can't display the site. The second problem is a missing switch plugin: without it, all domains lead to one context. Third is cache conflict: contexts share the MODX cache, so settings may overwrite each other. Solution: separate cache by context by enabling the cache_context option. Fourth: forgetting to set cultureKey for multilingual sites, breaking localization. Fifth: Nginx errors—wrong server_name directive or missing HTTP_HOST in fastcgi_param.

We take these nuances into account when doing the turnkey setup.

Context Setup Checklist

1. Create context and set parameters.
2. Bind root resource (site_start).
3. Configure switch plugin (domain/prefix).
4. Update Nginx (pass HTTP_HOST).
5. Test cross-context links.
6. Test switching.

What's Included in Turnkey Setup

• Audit of current site structure.
• Creation of contexts and domain binding.
• Development of switch plugin.
• Server configuration (Nginx/Apache).
• Content migration to new contexts.
• Documentation and admin training.
• 2 weeks of technical support.

Order turnkey MODX context setup. Contact us to discuss your project details. Get a ready solution in 2–3 days with a performance guarantee.