Replacing an Existing Site

[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]

Maybe you’re converting an Evolution site to Revolution (if you are, consider the GoRevo premium Extra). Even if you do use GoRevo, you can still use the method below. GoRevo is very good, but there are sometimes a few problems that need to be addressed after the conversion. You don’t want the site to be down while you handle them.

Rather than converting the original site with GoRevo, you can create a copy of the site in a subdirectory and do the conversion on the copy. That way all the problems can be solved before you activate the new site, which will be down for a very short time. In any event, you don’t want the site to be down for days or weeks while you build the new site. What’s the best way to handle this?

In my previous article, we looked at why all sites should be in subdirectories. This article will assume that you will be doing that.

There are actually a number of solutions to this problem. One way to go is to build the new Revolution site on top of the existing site, by renaming files and directories. This is almost always a terrible idea.

Another way to go is to build the new site in a subdirectory. When it’s ready, move all files in public_html somewhere safe, and copy the new site to public_html. We discussed the serious problems with this method in my previous article.

A third method is to have both the old and new sites in subdirectories. This makes the switch very fast and reverting to the old site even faster. This is the method we’ll be discussing in this article.

Important: Before embarking on any of the steps below, take a complete backup of the original site (both files and database).

My Method

This method works really well for me. The old site is down for just a few seconds before the new site is up, and it only takes a few seconds to revert to the old site if there are problems with the new one. It does require that all your sites be in subdirectories as recommended in the previous article.

In nutshell, you just create and work on the new site in a subdirectory. When the new site is finished, you edit four files, move the subdirectory under public_html rename the two subdirectories. See my previous article for more information on putting an existing MODX site in a subdirectory.

I once did this for an Evo to Revo conversion (before GoRevo existed). It worked really well, and I didn’t even have to create a virtual host, although in my case, the client’s original site was in a subdirectory I’ll call yoursite, reachable at yoursite.com.

Creating the New Subdirectory

Again, this assumes that the original site is also in a subdirectory.

Create a subdirectory called newsite under your original yoursite subdirectory - because your domain is already pointed at the public_html/yoursite directory it will be accessible with yoursite.com/newsite.

New MODX Install

Unzip the MODX files in the newsite directory, or use one of the installer scripts mentioned on the Forums to put it there. Be sure that the newsite directory contains the assets, connectors, core, manager, and setup directories.
Put this in the browser’s address bar: yoursite.com/newsite/setup. (If it’s a new install rather than a copy, you may need to create the database first).
If Setup goes well, leave the Setup directory in place. You may need it when you make the switch. For security, you may want to rename it once it has run.
You may need to manually create a new database if Setup can’t do it for you. Do this before running Setup again.
Once MODX is installed, you should be able to log in by going to yoursite.com/newsite/manager/.

For a Copy of the Old Site

Important: If you don’t create a new database for the site, most changes to the new site will also be changing the old site! I always create the database before running setup to give me better control of the character set and collation. The database can be a copy of the old database, but make sure the new database name and credentials are in the core/config/config.include.php file before launching the site!
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).
Delete all files in the core/cache director of your site and log off all users.
Copy all files in the old (yoursite) directory to the directory you just created: (public_html/yoursite/newsite.
Copy the /setup directory you extracted above to the subdirectory.
Run http://yoursite.com/newsite/setup. This will often straighten out the paths and URLs in the new site’s config files.
If the site doesn’t work, try visiting it in your browser’s private or Incognito mode.
If it still doesn’t work, in cPanel’s file manager, check the values in the following four files (see notes just below the file list):
- config.core.php (MODX root)
- manager/config.core.php
- connectors/config.core.php
- core/config/config.inc.php

For the first three, just change yoursite to yoursite/newsite in the MODX_CORE_PATH line. Be sure the line ends with a single slash (/).

For the core/config/config.inc.php file, change only the lines that begin with $modx.

Only for the ones that contain the word path, replace yoursite with yoursite/newsite (as you did for the first three files).

Change the $modx_base_url value from '/' to '/newsite/'.

For the other lines that contain url ($modx_assets_url, $modx_connectors_url, $modx_manager_url), you can usually leave them as is, since the base path is prepended to them. If you can’t get to the MODX Manager or the Manager doesn’t work properly, try adding /yoursite to the beginning of each value (this is often necessary on localhost installs).

If none of that works, you can hard-code the paths to the full path to each directory (you can see it in cPanel’s File Manager). I’ve never found this necessary except on localhost installs.

Other Issues

The modx_workspaces table in the database may have one or more hard-coded paths that need to be corrected (usually the path to the MODX core directory). Don’t edit it unless you have created a new database, since doing so may mess up the old site.

The .htaccess file often has references to the domain. You may need to modify them.

Building the New Site

This part is all done the normal way. All your Templates need this tag in the head section:

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

All internal links on the site must be in the form of link tags:

<a href="[[~12]]">Some Text</a>

The number in the link tag is the Resource ID of the Resource it points to (visible in parentheses next to the page title in the Resource Tree in the MODX Manager).

Putting It in Place

When the site is ready to replace the original, this is all you need to do:

Log out of both sites.
Delete all files in the core/cache directory for both sites (this will not bring the site down).
In cPanel’s file manager, edit the following four files (see notes just below the file list):
- config.core.php (MODX root)
- manager/config.core.php
- connectors/config.core.php
- core/config/config.inc.php
Modify the .htaccess file’s Rewrite Base line if your have modified it. Normally it will be just a slash: /.
Rename the yoursite directory to yoursite.old (site goes down at this point).
Rename the newsite directory to yoursite (site comes back up as the new site).
Delete all files in the yoursite/core/cache directory.

At this point, the newly developed site should be working fine at the new location. If not, double-check the paths in the four config files you modified. In the config.inc.php file, be sure not to confuse paths with URLs. It’s easy to do, and if a PATH constant is set to a URL, or a URL constant is set to a path, your site won’t work at all.

If everything is working, in cPanel, repoint the domain to the new site.

You can delete the old site (in the yoursite.old directory) now, but I like to leave it there for a while to make sure everything is OK with the new site and to serve as a backup. I change the old site’s site_status System Setting from “Yes” to “No” to disable the old site.

Don’t forget to change the System Setting back if you end up having to restore the old site.

Restoring the Old Site

The old site has not changed, so reverting to it is simple, though you may want to try the troubleshooting tips below if you don’t mind the site being down for a little longer. To revert to the old site, just, rename the new site to yoursite.bad. Rename the old site to yoursite and the old site is back up. Change its site_status System Setting to “Yes” (if you changed it).

Troubleshooting

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. That will often straighten out any errors in the config files. This will not affect the bobsguides.old site, so you can still restore it with the steps above.

If the setup directory is there after the switch (rename it back to “setup” if you’ve renamed it), you can run it with yoursite.com/setup. That will often straighten out any incorrect paths. If it’s been deleted, and you don’t have a copy, you can get it from the exact version of MODX the new site is running at modx.com/download. Older versions of MODX are available near the bottom of the page. Unzip the download somewhere else and copy the setup directory to the yoursite directory.

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 rare, but it could happen.

If both sites are MODX sites, you can copy the .htaccess file and the three config.core.php files from the old site (in yoursite.old) to the new site. You can’t do this with the config.inc.php file if you’ve created a new database for the new site because it specifies the wrong database and credentials. You can copy path and URL sections though. The old files should work with the new site as long as the old site is not a very old version of MODX (they may, or may not, work if the old site is an Evolution 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.