Why I Put All MODX Sites in Subdirectories

[From the Editor] The article that follows contains Bob's expert tried-and-true strategies for best managing MODX websites on traditional web hosting environments.

We'd be remiss in not mentioning that MODX Cloud was designed to eliminate the need for many of the things described below. In MODX Cloud you can create, deploy and upgrade individual MODX Revolution sites in seconds without any need to place things inside subdirectories or move things around. You can capture points-in-time Snapshots or all or part of a site, make a copy, or inject them into other sites. With Backstage™, you can work on, stage, and deploy content without ever logging into your production website. If you've never tried MODX Cloud for yourself, now's the time.

Of course, the reality is that circumstances may require us to work on hosting we didn't choose. As such, Bob's article will help make your life easier for those times when you are working on traditional or on-premise web hosting environments. [JG]

Some people prefer 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?

Why use a subdirectory in the first place? It’s easy to think of a site like a résumé. It will be modified slightly for different purposes and added to, but it’s always the same object. In my experience, though, websites 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 existing Evolution and Revolution sites will become Revo 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 résumé) 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.

Another way is to create the new site on a localhost install and transfer it to the live server when finished. This can seem like an attractive alternative, but I’ve found it increasingly unsatisfactory. It often involves moving many files in both directions and configuring two different installs with totally different root paths. There are a lot of moving parts, and it’s easy for things to go very wrong. In addition, it’s very difficult to implement this method without the old site being down for an indeterminate amount of time.

If you do move a local site to a remote location, zip up the files you want to move, upload the .zip file to the remote site, and unzip it there. Moving the files individually with FTP very often results in corrupted or missing files. A problem that’s very difficult to troubleshoot and solve.

Issues With Sites Not in a Subdirectory

Imagine that you have a site (yoursite) and a domain yoursite.com. The MODX files are in the public_html directory. In other words, you view the public_html directory, you’d see something like this:

public_html
  (directories)
    assets
    connectors
    core
    manager
  (files)
    config.core.php
    .htaccess
    index.php

If you want to make a copy of the site (say, to try out a new design), you’d copy all those files to a new directory (let’s call it newsite).

For another use case, say your original site is not a MODX site, but you’d like it to be one. You’d create a new MODX site in the newsite directory.

The new site won’t work until you point a domain at it. If you point your original domain at it, the old site will be down as you work on the new site. Nobody wants that. Not only does it inconvenience your users, but it also puts a lot of time pressure on you. Most people will tend to rush things, which can lead to disastrous results. If you have a spare domain name, you could point it at the new site, but if you don’t, you’ve got a serious problem.

Either way, you work on the new site in the newsite directory until it’s ready to replace the original site. You’d like it to be in the public_html directory. How do you get it there? You don’t want to rename the public_html directory, so you copy all the files in that directory to a new directory called “sitebackup” and the site is now down. You copy all the files from the newsite directory to public_html, but the site doesn’t work there because things need to be changed. The site is still down. You delete all the files in public-html and copy the old files back there, but that takes time, and the site will be down until the copy finishes. You go back to the newsite directory and work on the site. You may or may not get it right. You’ll have to repeat all the steps above over and over until it works, with the site down for each try.

A Better Way

This process is much simpler and less stressful if both sites are in subdirectories. In other words, the original site is in public_html/yoursite, and the new site is in public_html/yoursite/newsite (putting it there means that you don’t have to repoint any domains to work on the new site). The downtime for the switch is a matter of seconds (as is reversing the switch if things aren’t right).

I’ll give more details on this in the next article.

How?

New Site in Subdirectory

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 (yoursite).
Put the MODX files in the subdirectory.
In cPanel (or the equivalent), create an add-on domain (where you own the domain name) and point it at the subdirectory.
Run Setup (http://yoursite.com/setup).

I like to create the database before running setup. It gives me more reliable control of the character set and collation.

You may have to change the RewriteBase line in the subdirectory’s .htaccess file, but that’s usually only necessary for a localhost install.

Because the domain name is pointed it at the public_html/yoursite/ directory. People who visit the site always see yoursite.com in the URL, and MODX also thinks that’s the main URL for the site.

There’s good explanation of domains, virtual hosts, addon domains, and other things in the cPanel Docs here.

At this point, I should mention MODX Cloud, which will let you duplicate a site with a few clicks (using Cloud “Snapshots”). You can even move parts of a cloud site to another cloud site. And, you can spin up a new MODX Cloud site in less than a minute.

Using the Backstage feature of MODX Cloud, you can update your site (optionally collaborating with a team) without affecting the front-end until you have it the way you want, then deploy it with a few clicks. It’s definitely worth checking out, and you can try it out with a free preview.

Moving a Site From the Web Root to a Subdirectory

Important: If you’re moving an existing site, make sure the base href tag in every Template for any MODX site is called uncached (with the exclamation point (!)) like this:

<base href="[[!++site_url]]"/>

That makes sure an old or incorrect URL doesn’t hang around and cause problems.

You’ll also want to make sure that 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 should be doing that no matter how you structure your site(s).

Moving an existing site to a subdirectory is very similar to the process we described above, assuming that the domain yoursite.com is pointed at the public_html directory:

Make a complete backup of your site, both files and database.
Download the exact version of MODX you’re running from modx.com/download (previous versions are there near the bottom of the page). Put it in a safe place and extract the files there (this is so you’ll have the correct version of the /setup directory).
The original site in the web root will not be changed and will remain up until you repoint the domain, so there’s no need to rush these steps.
Delete all files in the core/cache director of your site and log off all users.
Copy all the files to the subdirectory.
Copy the Setup directory you extracted before to the subdirectory.
Run http://yoursite.com/subdirectory/setup. Important: Do not proceed with Setup unless you can check “Upgrade Install”. Otherwise, MODX thinks its a new install and may wipe out your database.
If everything works, point your domain at the subdirectory. If not, check the values in the four config files listed below (see my following article for more details). Try visiting the subdirectory site with your browser in private or incognito mode to make sure the browser’s cache and cookies are not causing the problem.
You may have to add the subdirectory to the .htaccess file’s RewriteBase line (/subdirectory/), though this is usually only necessary on localhost installs:
- config.core.php (MODX root)
- manager/config.core.php
- connectors/config.core.php
- core/config/config.inc.php
When everything is working in the subdirectory, point the domain at the subdirectory.
Important: Delete the Setup directory.

The .htaccess file often has references to the domain. You may need to modify them, especially if FURLs are turned on.

Coming Up

In my next article, we’ll discuss the mechanics of replacing an existing site, with information on FURLs and troubleshooting problems in the new site.

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.