Using MODX Contexts to Host Multiple Sites on One Installation

Why Contexts Matter for Multi‑Site MODX

When you need separate websites—different base URLs, resource trees, and site settings—yet want to keep a single MODX core, database schema, and manager interface, the Contexts feature is the built‑in solution. Contexts isolate front‑end routing, resource lookup, and context‑specific settings while sharing core files and user tables.

Requirements & Scope

• Each site must expose a distinct base URL (e.g., https://blog.example.com vs. https://shop.example.com).
• Resource trees should be separate so that editing a page on one site cannot affect another.
• Site‑specific settings (site_name, error_page, etc.) must be changeable per site.
• The manager, connectors, and core files are shared; only context‑specific data lives in modx_context_setting.

The Minimal Design

1. Create a new context in the Manager: Context Key (e.g., sales), Context Name, and set base_url to the target path.

2. Add a context setting to map the HTTP host to the context: http_host => shop.example.com. You can also use http_host values like www.shop.example.com or sub‑folder patterns.

3. Create resources with the context_key set to the new context. The MODX router will then resolve URLs under the new base URL to these resources.

Trust & Data Boundaries

Core files and shared tables (e.g., modx_user, modx_session) reside in a single database schema. Context‑specific data lives in:

• modx_context_setting – key/value pairs unique to each context.
• Resource table entries with a context_key column pointing to the context.

Manager policies can restrict which users see which contexts. The front‑end router uses the context_key to isolate resource lookup, preventing accidental cross‑context data leakage.

Operational Checks

1. Verify HTTP host mapping: Load a URL that matches the http_host setting and use a plugin snippet to print $modx->context->get('key'). It should match the context key you created.
2. Cache validation: After changing a context setting, clear the manager cache via Clear Cache or run php modx-cms/cli/clear-cache.php from the console. Context cache keys include the context key, so clearing one does not wipe another.
3. Plugin load order: Ensure that any plugin that accesses $modx->resource runs after the OnHandleRequest event, so the context is already initialized.

Concrete Example

Assume you want a second site at https://shop.example.com sharing the same MODX instance.

# In the Manager: Contexts → New
Context Key: sales
Base URL: /
# Add Context Setting
Key: http_host
Value: shop.example.com
# Save

To create a resource under this context:

# In Resources → New
Context Key: sales
Template: 2 (optional)
Content: <p>Welcome to the shop!</p>
# Save

Now visiting https://shop.example.com/your-resource-slug will resolve to that page. In a plugin you can check:

if ($modx->context->get('key') == 'sales') {
    // Perform shop‑specific logic
}

Failure Modes to Watch For

• Missing or incorrect http_host setting: MODX falls back to the default web context, causing 404s or serving the wrong site.
• Wrong context_key on a resource: The resource becomes inaccessible under its intended URL.
• Plugins running before context initialization: They may access the wrong resource or site settings.
• Cache stale data: If you modify a context setting but forget to clear the cache, the change will not appear until the cache expires.

When the Context Approach Is Insufficient

If you require true data isolation—separate tables or databases—or distinct manager branding per site, the single‑context model won’t suffice. In that case, consider:

• Running separate MODX instances, each with its own database.
• Using a multi‑tenant manager extension that provides per‑site UI customizations.

Security & Least‑Privilege Practices

Because all contexts share the same database user, a compromised manager account could modify any context setting. Mitigate by:

• Assigning manager policies that limit users to specific contexts.
• Auditing changes to modx_context_setting via database triggers or external logging.
• Regularly rotating database credentials and using a dedicated read‑only user for front‑end operations.

Practical Verification Checklist

• Confirm the new context appears in modx_context table.
• Check modx_context_setting for the http_host entry.
• Visit the site’s URL and verify the page loads.
• Run a plugin that echoes $modx->context->get('key') and compare to expected value.
• Clear cache and reload to ensure changes propagate.

Conclusion

Contexts give you a lightweight, supported way to host multiple sites on a single MODX installation while keeping resource trees and settings isolated. By following the design steps, respecting data boundaries, and performing the operational checks above, you can avoid common pitfalls and maintain a clean, secure multi‑site environment.