Hosting Multiple Subdomains on MODx Revolution

This write up gives you a step-by-step of how to set up and run multiple subdomains on a single instance of MODx Revolution. This process was created using the official documentation, along with some other helpful tricks that I added to make possible for anyone to do without root server access.

Update: Feb 11, 2011 — If you’re interested in hosting multiple top-level domains, the new write-up is here.

Before We Begin

In order for this to go smoothly, you should have a few things already taken care of.

  1. Make sure that you have a wildcard (*) A Record created in your DNS Zone. If you don’t want to fool with wildcards, use your control panel to create the subdomains in your hosting control panel (although you won’t be using the real subdomains).
  2. You must have FTP or File Manager access to the location where your MODx install lives.
  3. Download and install MODx Revolution, already. I’m going to start with a fresh install of Revo. This tutorial uses RC-1, so the instructions you see here will likely apply to the final release.

Let’s Get It Started

When you first visit your Manager, you’ll see the ‘web’ container in the nav area. This is the context that houses the default main site of your MODx installation.

The default ‘web’ context with basic pages added.

Our goal will be to create several of these “home folders” one for each subdomain that we will create. So, let’s go!

First we need to visit the ‘Contexts‘ menu, located at System > Contexts.

Click to Enlarge

The Context area lists the default contexts: the ‘web’ context, which is the main site, and the ‘mgr’ context, which is the backend manager that we’re using to do this.

Click on ‘Create New‘ and we’ll create our first subdomain. The ‘Content Key‘ refers to how you want your context to appear in the sidebar and how you will refer to it when you tell MODx to go there. This should be simple and include no spaces (and preferably no caps). I typically name it the same as the submdomain I’m planning to use just because it makes things easier to remember (although these two names have no impact on one another). For this example, I entered the following:

If we refresh the resource list (using the green “recycle” arrows), we see our new context appear along with the original ‘web’ context. This will be the home of our first subdomain. Go ahead and create the minimal pages needed. I generally start with an index and an error page to get started. You can use the new ‘Quick Create’ feature by right-clicking the new context and choosing ‘Quick Create > Document‘. I typed the following:

As you can see, I typed something in the content area that will let me know that it’s successful when I go to test the subdomains later.

My resource list now looks like this:

The Setup

To get this new context to actually behave like a website, we need to edit it and add a few necessary variables. So go back to your list of contexts (System > Contexts) and right-click the new context you created. From the pop-up menu, choose ‘Update Context‘. Once there, you should click on the green tab for ‘Context Settings‘.

Location of Context Settings Tab

Click on ‘Create New‘ and we’ll begin adding the variables that we will need, one at a time. When the ‘Create New‘ dialog pops up, the only settings you need to worry about are the Key, Name and Value. Everything else goes untouched. I add a description just for kicks, but the main site’s description will usually override this description anyway.

Do this once for each of the following settings:

site_start – the ID of your new context’s homepage.
base_url – Set this value to “/” (no quotes) since we’re making the root of the URL our base.
http_host – Set this value to “” (your subdomain url)
site_url – Set this value to “” (FULL subdomain url). Must have trailing slash.

Note: You might recognize some of these variables, as they are simply overrides of options currently defined in the settings for the main site in your MODx installation. You can add any settings that you wish to customize for each site such as Default Template and Error Page.

Here are my finished settings.

Click to Enlarge

Now We Make It Tick

So, let’s create a folder in our server to create a place where the subdomain’s files will live. We’ll place it in the same directory where modx is installed and give it the same name as our subdomain. My folder is called ‘subdomain1’ for this example.

Inside this newly-created folder, you will need to copy a few files from the MODx root directory:


Now, we edit these files so that they handle things properly when they’re accessed. Basically, we need to make them behave as if they were root folders.

Edit .htaccess

Make sure that RewriteBase is set to “/” with no other folder names behind it. (In most cases, it will probably already be set correctly.)

Edit index.php



Change to


Change the context name to match whatever you named your context in the manager section.

Edit in config.core.php


define('MODX_CORE_PATH', dirname(__FILE__) . '/core/');

Change to

define('MODX_CORE_PATH', '/home/example/public_html/core/');

Use the full web path to your site’s core folder. If you don’t know your site’s full path, check your control panel or hosting welcome letter. This information should be readily available with your account.

At this point, everything should be working smoothly and you can test the success of your setup by accessing and you will see the contents of your main page.

In my case, I got the “This is Subdomain1” text that I typed as a success message. So, I’m in good shape!

Routing Subdomain Traffic to the Proper Folder

Now that we have all of our settings in place and our folder created, we just need to tell the server where to redirect this traffic to so that we can be sure our visitors don’t see the main site when they access this url. In the official documentation, they describe how to do this in your Apache Config File. I got mine working that way, but it was a huge pain. I wanted to find a way that would work without needing to hack around in Apache. Not to mention, most users do not have root access to their config files.

After several days of searching, I came across a regex hack from jdmorgan at WebMasterWorld that could be placed in the htaccess file. The script will take any traffic that comes in through a subomain and redirect it to a subfolder that matches that subdomain. This turned out to be exactly what I needed since I wouldnt want my subdomains to have to share folders and files with the main site anyway. That would be a disaster waiting to happen.

Place the following script in the .htaccess file that resides in the MAIN folder of your MODx installation. This does NOT belong in the .htaccess files of your subsequent folders. Add this to your .htaccess AFTER the Friendly URLs code or it will break Friendly URLs

RewriteCond %{HTTP_HOST} ([a-z0-9][-a-z0-9]+)\.yourdomain\.com\.?(:80)?$ [NC]
RewriteCond %{DOCUMENT_ROOT}/%1 -d
RewriteRule ^(.*) %1/$1 [E=SUBDOMAIN:%1,L]

If you had success above when accessing your subfolder directly, you will be equally rewarded when you visit, where you should see the contents of your subdomain’s home page.

Now that you have this working, you can repeat this process as many times as you wish to launch any number of subdomains within your MODx installation.

Our next task is that of hosting completely different domains inside a single MODx installation.


Error 503

If you’re getting an Error 503 when you access either the subfolder or the subdomain, then you need to check your config.core.php file. If the path there is not specified correctly, you will get this error.

You might also check that the Context settings you created are correct.

Subdomain Not Displaying Sub-folder Contents

To be sure our redirect script is working, try adding a simple HTML file into your subfolder and accessing it via the subdomain (without folder name in URL). If you get a 404 error, then your site does not have a subdomain or wildcard set up.



  1. julie writes:

    Thank you for this detailed post. I had followed the tutorial here: but there are a few holes in the steps in that tutorial that you have filled – the .htaccess file and the changes to index.php in the subdomain folder. THANK YOU!

  2. .abelafonte writes:

    Glad it worked for you! I have seen but if I’m not mistaken, his tutorial outlines the steps for setting up multiple top-level domains.

    That process only needs the primary index.php so it’s fewer steps. It’s actually an easier setup.

    When I have time, I’ll be writing my own version of that method so readers will have both solutions.

  3. Matthew writes:

    How would the rewrite rules change if using IIRF as a rewriting tool on IIS? The subdirectory took me where I wanted to go, but when I type in the subdomain, it takes me to the root index page.

  4. .abelafonte writes:

    Unfortunately, I don’t have any experience with IIS.

    There might be someone on an IIS forum that could help.

  5. Lindani Moya writes:

    Thanks for the Tutorial easy to follow thought you might want to also add site_name to the settings. so that the pages on the subdomain display the correct title e.g “Domain Name – Home”

  6. sintl writes:

    I have godaddy hosting,modx 2.0.7pl. I have (*)dns setup and subdomain1 setup pointing to /. Along with this i have been able to follow the steps but my preview page of index on subdomain1 points to back to my homepage on main site. How should I resolve?pls guide


  7. moniarde writes:

    Good tutorial, I have a problem tho; all of the links (imgs, css, js, etc) can’t be found. The 404 error I get says it’s looking for the link in the subdomain folder. How do I fix this?

  8. Domains | writes:

    […] the approach Wordpres-MU tries to accomplish, but as always, MODx does it better , check it out. MODx Multi Domain Tutorial on This entry was posted in Archived – MODx, MODx Revolution by admin. Bookmark the […]

  9. Sintl writes:

    Used this tutorial successfully for sub domain. Have read at various places folders are more effective way for seo purpose. That said we do create separate folder in this method but with sub domain links. Is it possible to use this solution for folder wise. foreg

    Would you please do a tutorial on that as well.


  10. Chris Were writes:

    It works for the page directly under my sub-domain, but when i try and change to a 2nd page in the sub-domain it chucks me back to my original domain’s homepage. Probably my own dumb fault though.

  11. Chris Were writes:

    Just found out it is my fault. This method doesn’t appear to work with friendly urls