Hosting Multiple Subdomains on MODx Revolution

April 18, 2010 | Tags for this entry: MODx, web development

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 “subdomain.yourdomain.com” (your subdomain url)
site_url – Set this value to “http://subdomain.yourdomain.com/” (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:

.htaccess
index.php
config.core.php

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

Find

$modx->initialize('web'); 

Change to

$modx->initialize('subdomain1');

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

Edit in config.core.php

Find

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 http://www.yourdomain.com/subdomainfolder/ 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

#REDIRECT SUBDOMAIN TO SUBDIRECTORY OF SAME NAME
RewriteCond %{ENV:REDIRECT_SUBDOMAIN} =""
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]
RewriteRule ^ - [E=SUBDOMAIN:%{ENV:REDIRECT_SUBDOMAIN},L]

If you had success above when accessing your subfolder directly, you will be equally rewarded when you visit http://subdomain.yourdomain.com, 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.

Troubleshooting

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.