Some people prefer (and will advise you) to put MODX sites in the server’s web root (public_html) whenever possible. There’s nothing wrong with doing that, and it can save you a few steps, but I’m going to argue against it in this article. I’ll also cover how to set up a MODX site in a subdirectory.
Why use a subdirectory in the first place? It’s easy to think of a site like a resume. It will be modified slightly for different purposes and added to, but it’s always the same object. In my experience, though, web sites over time are almost never like that. Even a simple “brochure” site will often go through several transitions. CMS platforms come and go. WordPress sites become MODX sites, MODX Evolution sites become MODX Revolution sites. Many Evolution and Revolution sites will someday become MODX 3 sites. It’s also common to create a new, working version of a site to show a client.
Working on the site in place (as you might with a resume) is fraught with peril at best, and impossible at worst. Trying to convert a MODX Evolution site to MODX Revolution in place would be a recipe for disaster. Converting a WordPress site to any version of MODX in place would be like living inside an H.P. Lovecraft story for weeks on end.
What you want is to create the new site somewhere else, then switch to it when it’s finished. It’s possible to do this with one version in the web root and one version in a subdirectory, but it’s simpler if they are both in subdirectories, and the down time for the switch is a matter of seconds (as is reversing the switch if things aren’t right).
Imagine that you have a site called Bob’s Guides and it can be reached at this URL:
http://bobsguides.com. Imagine, too, that the files for the web site are in a subdirectory called “guides” under the web root (i.e.,
public_html/guides). When you set this up and bought the domain, you went into cPanel and set up an add-on domain for bobsguides.com and pointed it at the
public_html/guides/ directory. People who visit the site always see bobsguides.com in the URLs, and MODX also thinks that’s the main URL for the site.
Now, you want to work on a new version of Bob’s Guides. Maybe it’s a switch from a different CMS to MODX Revolution. Maybe it’s a new design you want to show to a client. Maybe you want to try a different database strategy. Whatever the reason, you can just create a new copy of the site in a directory called guides2. You can (and should) run setup at
http://guides2.bobsguides.com/setup and you can access the MODX Manager at
If you have a spare domain name, you can point it at the
guides2 directory. If not, you can continue to use the URL in the paragraph above as you work on the site. Creating a virtual host with a spare domain name will solve one problem with Friendly URLs (FURLs) for you. If a domain is pointed at the subdirectory, you can usually leave the
Rewrite Base line of .
/. Then you won’t have to change that when you replace the old site with the new one.
If you don’t create a virtual host and continue to use
http://guides2.bobsguides.com and you want to implement FURLs, you’ll usually have to change the
Rewrite Base line in
/guides2/. Don’t forget to change it back to
/ before phasing in the new site.
Once the new version is finished and you want to make the switch, all you need to do is perform the following steps:
- Log out
- Delete all the files in the core/cache directory
- Edit the values in these 4 files and replace guides2 with guides. Be sure to get them all.
- config.core.php (MODX root)
- Modify the
Rewrite Baseline in the
.htaccessfile (if necessary)
- Rename the guides directory to guides.old
- Rename the guides2 directory to guides
The site will be down for only as long as it takes you to issue those last two commands. If anything goes wrong, you can have the old site back up in a few seconds by performing just these two steps:
- Rename the guides directory to guides2
- Rename the guides.old directory to guides
Note that as long as you keep the old directory there, you can always revert just by doing the rename. Things happen to sites. They get hacked, they get broken by upgrades, they get broken by installed extras, and sometimes they get broken for reasons that take several days to figure out. It’s a real comfort to know that you always have a full, older version you can go back to just by renaming a couple of subdirectories.
This technique will only work if all internal links (links to pages on your site) are in the form of link tags (in this example, 12 is the Resource ID of the resource you’re linking to):
<a href="[[~12]]">Some Text</a>
You’ll also need this tag in the
section of all templates:
<base href="[[++site_url]]" />
In the case of multi-context sites, that should be:
In addition, all extras as well as snippets and plugins you write yourself need to use the MODX constants to calculate paths and URLs. Here are the most common ones:
Virtually all MODX extras can be counted on to use the constants, but make sure you’ve used them if you’ve written any of your own snippets or plugins that require a path or URL.
Placing a MODX site in a subdirectory is quite easy. Here are the basic steps (assuming that you already own the domain name and it’s pointed at your host):
- Create the subdirectory under public_html
- In cPanel, point the add-on domain at the subdirectory
- Install the MODX files in the subdirectory
- Run Setup
FURLs in a Subdirectory
As mentioned above, if you implement Friendly URLs (FURLs) on your site, you may, or may not, have to modify the
Rewrite Base line in the site’s
.htaccess file. The default value is
/. In my experience, this works fine on remote servers as long as the domain is pointed at the subdirectory, though there are cases where you need to change it to something like this:
Rewrite Base /subdirectoryName/
In particular, you usually need to make that change for
localhost installs where you don’t have a virtual host set up. On
localhost, it’s often easier to modify the
.htaccess file than to set up a virtual host.
If the site doesn’t work after the switch, the first thing to try is deleting all files in the core/cache directory and using the incognito or private mode in your browser. If that solves the problem, clear your browser cache and cookies. If it doesn’t, try running Setup again in upgrade mode at the new location.
If that doesn’t do it, double-check the paths and URLs in the four config files listed above.
If you’re still having trouble, you may have an extra that has a hard-coded path in its code or in a System Setting or property. This is quite rare, in my experience, but it could happen.
In the next blog article, I’ll go into more detail about doing a full site replacement.