In this article: Introduction, Prerequisites, How my file system is structured, Creating the repositories, Linking to the repositories, Recap, Common problems and fixes, Maintaining your repositories, Using this technique with ZenPhoto and other CMS systems, Additional resources, Comments and feedback

Introduction

WordPress is a wonderful blogging platform and, in certain situations, a good choice for a general content management system (CMS). It is easy to end up with several parallel installations of WordPress—one for each major topic you want to discuss. Everything works great at first, but after a while, the constant barrage of updates to the main application, various plug-ins, and the themes becomes something of a management nightmare. The more blogs you operate, the more time is spent maintaining the blogging environment and the less that is available to actually blog.

If you host your WordPress blog on a Linux-based server (BSD or most any other Unix-like operating system should be able to do this equally well) and you have “shell access”, I might have a way to ease your pain. In a nutshell, you will create a central repository containing every WordPress plug-in that you use in all of your blogs. You create a separate repository containing each of your themes. Next, you create symbolic links (think of them as shortcuts; more about them in just a moment) from each installation of WordPress to your central repositories. From that point on, you only have to update your plug-ins and themes once, and the change will take effect instantly across all your sites. It’s a very slick trick!

This trick works probably works well on many other CMS systems that use plug-ins and themes; I have started using it with my ZenPhoto installations, too. In addition to helping keep things updated, it also saves disk space since you are only maintaining a single copy of the files on your server.

I will provide step-by-step instructions and some quirks for which you need to be aware. One quick word of caution: mistakes, bugs, and goofs can also instantly affect all your sites, so be very careful as you work, take your time, and always backup your files and databases before you start.

Prerequisites

Before we get started, make sure that your system meets the following requirements:

• All of your WordPress installations should be hosted at the same Internet Service Provider, and they probably have to be on the same physical server (though not necessarily with some ISPs depending on how they configure things). If the server is something other than Linux or Unix-like system, they may even have to be on the same physical hard disk for this to work. Ideally, they should all be hosted under the same user account, but if not, they different accounts need to be in the same Unix security group and permissions have to be granted for the whole group, not just the owner (that’s beyond the scope of this article).
• You must have shell access to your server. This means that you can access a command prompt (a screen that looks like a DOS window) after you login, and you can type commands that directly affect your server. These instructions assume that your server is a Linux system, though FreeBSD and other Unix-like systems should all work similarly. While Mac OS has similar features, I think the commands are somewhat different, so you will need to adapt these instructions if your server is a Mac. Windows is finally getting to the point that this type of linking may soon be available, but as of Server 2003, this method will not work on a Windows server.
• It is also very helpful if you have some basic familiarity with your server’s shell and the structure of the file system on the server. These instructions are based on the way things are setup on my Internet Service Provider’s servers, and your ISP might do things a little differently. If you get lost or confused midway through the process, you will want to be experienced enough to figure out how to undo the things you did so far.
• If you need a program to connect to your shell account, I recommend PuTTY. It’s a little overwhelming with all the options it has, but you can pretty much ignore them, enter the address to your server, and hit connect. Voilà! You should see a prompt to enter your username and password. If your ISP supports it, I recommend connecting using SSH, which provides an encrypted connection for better security (though it’s beyond the scope of this article to explain exactly how you do that).
• I find that some things are easier to do using a good FTP program (I love Filezilla for this purpose), and other things have to be done using the shell. In particular, I like to create the central repositories by clicking and dragging files around in Filezilla rather than typing lots of commands in the shell.
• Your server has to support symbolic links (also known as “symlinks” or “soft links”). Under most Linux/Unix-like operating systems, you use the command ln -s to create the symlinks. To test if you have this command, type ln --help from the shell; you should see the help screen for the ln command. If you get an error and did not make a typo, your system may not support symlinks.

–Top–

How my file system is structured

Before I go in-depth with instructions, I’ll briefly explain how files are arranged on my ISP’s server. Your ISP hopefully arranges things for you in a similar manner.

When I login to my command shell and use the ls command (ls is short for “list”, which brings up a list of all the files in the current directory), I see a number of directories—one for each domain that we host (allogro.com, willmurray.name, etc.). The actual content of each website is contained within its directory (i.e., the directory “allogro.com” contains all the files for the allogro.com web site and the directory “willmurray.name” contains everyting for the willmurray.name site.

If I print the working directory (pwd), I see the full path from the root of the server (the top of the file system) all the way to my account’s home. In my case, the path is: /home/acanthus. Our sites are hosted with DreamHost, a very large ISP based in Los Angeles, California (some people hate them, but we have been extremely happy with them for over 3.5 years). In this case, the first slash is the root of the file system. home/ is the place that all the hosting customers’ accounts are stored. acanthus is the “home directory” of our account. The allogro.com and willmurray.name directories reside underneath the acanthus directory.

The home directory is a special place, because it is outside of any website and not directly accessible from the web. It’s a good place to store things that should not be peeked into by curious visitors or overzealous search spiders. In fact, unless DreamHost really screwed up or I created a link into the home directory, it would be a safe place to store passwords and other fairly sensitive information. It is also an ideal place to store our shared repositories for WordPress.

–Top–

Creating the repositories

Repository directories

You will want to start by creating your repositories someplace inaccessible to casual web visitors. If you have a home directory like I described above, that’s perfect and recommended. If not, you could create a new directory and try to protect it using .htaccess and robots.txt files along with other techniques to keep people out of it (though this is not a very secure method, and it could leave your repositories subject to attack).

Using Filezilla, I created a directory named shared (the full path is /home/acanthus/shared) to hold all the files that are shared between different web sites. Under that directory, I created two more directories: wp_plugins and wp_themes (that’s /home/acanthus/shared/wp_plugins and /home/acanthus/shared/wp_themes). In each case, I set the file attributes of these directories to give the owner full permissions (rwx) and the group and public permissions to read and execute (r-x, don’t want visitors to be able to make changes). (If you prefer numerical permissions, that’s 755.)

wp_plugins will become the home to all of your WordPress plug-ins. If you use certain plug-ins in one blog, but not in others, go ahead and add the plug-in to this repository. Within WordPress you will enable only the plug-ins you want to use; any that you don’t want to use should just remain disabled. wp_themes is the same deal, except that you store your themes there (that should be self-evident, I hope).

Best practices

Be sure to disable write access to plug-in and theme files and directories unless they specifically require it. For directories, only the owner should have write access (755). For files, you also want to disable the execute permission (644). Check the documentation for each plug-in to see if it needs write access. If your plug-in breaks or has errors about being denied access, you probably need to loosen the restrictions a bit on a directory or some files for the plug-in to function. Very few themes seem to need write access (only one that I’ve ever encountered).

I highly recommend that you grab fresh copies of each plug-in and theme that you plan to use. This way you won’t copy bugs over from existing installations and you are certain to have the latest (and hopefully bug-free) version of the software available. Alternately, you can use the shell to copy (cp) or move (mv) existing directories into your new repositories (though I don’t recommend doing so, and it can leave your site broken until you complete the whole change). You could also use Filezilla to download your plug-ins and themes directories from your current WordPress installation(s) and upload them (thus creating a copy) to your new repositories. If you have heavily customized a plug-in or theme, this may be your best option.

When I upload plug-ins, I usually change the directory name to include the version number. So, if you are uploading version 1.2 of the myplugin plug-in, I’d rename the directory to myplugin.1.2. Some plug-in authors do this for you automatically, while others try to make it easy for people to upgrade by keeping the directory names the same. In a shared repository, though, this can actually cause you problems. One caveat is that some plug-in authors hard-code their directory names in their plug-ins (shame on them!), and renaming the directory breaks the plug-in. In that case, you will either have to hack the plug-in to use the updated directory name, leave the directory name unchanged, or pester, er, petition the author to not hard code the directory name in future releases.

Why worry about version numbers that way? Well, I like to test new versions of plug-ins on a low-traffic blog before introducing them to one of the more active blogs. Remember that when you make a change in the repository, it immediately affects ALL of your blogs. So by overwriting a plug-in with a newer version, you are essentially upgrading all your blogs simultaneously. If there’s a glitch in the new plug-in, then all your blogs will be affected instead of just one. By uploading the plug-ins to different directories, you can disable and enable plug-ins on a per-blog basis. Then, once all your blogs are using the new version, you can safely delete the old version from your server to save space.

Most plug-ins also require you to disable them before you install the newer files, and then re-enable them after everything is in place. With a shared repository, that means you have to go to each blog and disable the old plug-in, then upload, and then go back to each blog to re-enable it. I prefer the flexibility of making changes one blog at a time if I want.

–Top–

Linking to the repositories

So now that you have your central repositories all setup with shiny new copies of all your plug-ins and themes, how do you use them? It’s pretty easy, even if the command you type is a little cryptic.

Note: I recommend starting and fully testing this on your lowest-activity blog first to get the hang of it and minimize downtime on your busiest blogs.

Preparing WordPress

Start by logging into WordPress and disabling all of your plug-ins (there is a link at the bottom of the page to disable all the plug-ins at once). This is important since the path to the plug-ins and even the versions might be different when we are finished than what is in use now.

Locate your repositories

After that is finished, login to your ISP’s shell prompt using PuTTY or your favorite program.

Print the working directory (pwd is the command to do this). If your ISP includes that information in the command prompt, so much the better! Otherwise, jot down the path to your home directory (the place you are when you first login). In my example, that will be /home/acanthus.

List the directory (ls is the basic command, though I find ls -lp to be a more useful view). Hopefully you will see your “shared/” directory (or whatever you named the directory that holds your repositories). Next, list your shared directory (ls -lp shared is the command I would use), and be sure that you can see your repositories within it.

Now I need to go to the wp-content directory of my WordPress installation. I would type cd allogro.com to change directories to the allogro.com site. I keep the blog under a directory named main, so next I would cd main. The wp-content is inside this directory, so I would cd wp-content. Note: I could have strung that all together into a single command (cd allogro.com/main/wp-content), but I usually prefer to go one level at a time so I don’t make mistakes.

Listing the directory (ls -lp) shows that I am, in fact, in the correct place, and there are folders named “plugins” and “themes” already here. That’s good! We need to rename those directories to get them out of the way of our new links. We do that by moving the directories to the same location with a different name (a fairly round-about way of doing it, but it works). Enter the commands mv plugins plugins.disabled and then mv themes themes.disabled. At some point in the future after everything is working, remember to come back and delete these disabled directories.

Create the symlinks

Now it is time to create the symlinks to your shared repositories. This is where you need to enter the full pathname to your folders, so start by verifying that you can see all your shared plug-ins: ls /home/acanthus/shared/wp_plugins (substitute your own path, of course). The command to create the symlink is almost identical: ln -s /home/acanthus/shared/wp_plugins plugins (again, substituting your own path).

Let me explain that carefully. ln -s is the command to create a symbolic link. Be sure to use lowercase letters, because uppercase will not work correctly. Also, be sure to include the “-s”, or the system will attempt to create a hard link instead of a symbolic link (which is not what you want), and will likely generate an error on most systems (unless you are logged in as “root” on your own server, and then you might cause yourself problems). Next, you give the full pathname to the target (the shared plug-ins repository). You technically could use relative paths (if you know how those work), but full paths seem to be more stable for plug-ins. The final part is the name of your new link. Since WordPress expects your plug-ins folder to be named plugins, that’s what we used.

If you did not get an error message, when you list the directory (ls -lp), you should see that the entry for plugins looks something like this: plugins -> /home/acanthus/shared/wp_plugins/ (with the file attributes set to give everyone full access as indicated by “lrwxrwxrwx”, but that’s not a problem since the permissions on the repository are what matter, not the ones on the symlink). This means you have successfully created a symlink to your repository folder. List the contents of that folder (ls plugins) and it should exactly match the contents of the repository, since they are actually the same folder just with a new link.

Now it’s time to link to your themes: ln -s /home/acanthus/shared/wp_themes themes (once again, substituting your own path for mine).

Configure and test WordPress

Go back to the administration area of your WordPress blog. Under presentation, you should see a list of all the themes you uploaded to the shared themes repository. If you do not see any difference, you might need to clear your browser’s cache and refresh the page. Simply select your desired theme to activate it. Even if your desired theme came up automatically, it might be a good idea to select a different theme momentarily, and the reselect your desired theme. This sometimes fixes weird problems I’ve encountered, so doing it right now rather than later makes sense. View the blog and make sure things look right.

You might have to reconfigure your widgets since you changed themes. Some widgets might not work or be available until you activate a related plug-in.

After you are sure your theme is working, go back to the plug-in administration for your blog and enable one or two plug-ins that you can use to easily verify your plug-in repository is working. If those two look good, you can enable one or two more plug-ins and then test them. Repeat until all the desired plug-ins are verified.

If after enabling a plugin you see warnings that a path could not be found, and if you renamed the plug-ins’ directories to include their version number, you might have to rename the plug-in directory back to its original name to get the plug-in to work again.

–Top–

Recap

These are the steps anytime you want to have WordPress use your shared repositories instead of a stand-alone installation. If you have followed my instructions all the way so far, then you will repeat the following steps for each of your remaining blogs. Again, I recommend working in order from the blog with the least traffic to the one with the most to minimize downtime for your visitors as you become familiar with the process.

This recap assumes that you have already created your shared repositories and just need to link to them now.

1. Disable all plug-ins in WordPress.
2. In the shell, navigate to the wp-content directory of your blog (e.g., cd willmurray.name/blog/wp-content; use your own pathname).
3. Rename the current plugins and themes directories (e.g., mv plugins plugins.disabled and mv themes themes.disabled).
4. Create the symlinks (e.g., ln -s /home/acanthus/shared/wp_plugins plugins ln -s /home/acanthus/shared/wp_themes themes; use your own pathnames)
5. In WordPress, activate your theme (if it’s already active, change to another one, then change back to your desired theme).
6. Reconfigure Widgets if necessary.
7. Activate one or two plug-ins at a time and test as you go

Note: After you have a plug-in working in one copy of your blog, it should work in all copies.

–Top–

Common problems and fixes

Redirect URLs generated by plug-ins to the correct subdirectory using .htaccess

Some of my blogs are at the root of the site (www.example.com/), while others are in subdirectories (www.example.com/blog or www.example.com/main). Some plug-ins assume that your site is at the root, and they do not work correctly otherwise. I have been able to fix this in most cases by adding a redirect in the root-level .htaccess file of sites where WordPress is not at the root, and redirect requests for /wp-content to the appropriate subdirectory (/blog/wp-content or /main/wp-content).

Relative paths leading outside the plugins directory cause problems

Some plug-ins use relative paths to files outside of the wp-content/plugins folder (i.e., they try to access a file in the main WordPress installation directory). Without editing the plug-in, there’s really no way to fix this problem. If you are up to hacking the plug-in, you could add a new variable at the top of your theme’s index.php file that gives the full pathname to your local plugins directory (well, it’s actually the symlink to your shared repository, but WordPress doesn’t know that or care). For example, you could add the following to your index.php

< ?php $SHARED_PLUGINS="/home/acanthus/allogro.com/main/wp-content/plugins/"; ?>

Then go though the plug-in files and add the $SHARED_PLUGINS variable in front of each reference to a relative path. Example:

/* Old code:
require_once('../../wp-example.php);
New code: */
require_once($SHARED_PLUGINS . '../../wp-example.php);


–Top–

Maintaining your repositories

The whole point of this exercise was to make it much easier to keep your plug-ins and themes updated across multiple sites. (Oh yeah! That’s why I just went through all of this.) Here’s how easy it is to update everything nearly instantly…

When you are in the plug-ins administration area and notice that a plug-in has an available update, go fetch it, extract it, and rename the directory to include the version number of the release. Upload the plug-in to your repository using FTP. Refresh the plug-ins administration page. You should see both the old version of the plug-in (still active) and the new version (not yet active). Disable the old version. Enable the new version. Test.

If something broke, it’s probably because the plug-in has its directory name hard-coded within it (not a good thing for several reasons). You will have to disable the plug-in in ALL your blogs, then replace the old version with the newer version as instructed by the author. Then you can enable the plugin in each blog. Not as elegant, but still only one upload to worry about.

When you are happy that everything worked, go to your other blogs whenever you want, and disable the old version and enable the new version. There’s no extra uploading to do. If you need to tweak a plug-in for any reason, you only have to do it once, and the tweak takes effect instantly on all of your blogs.

–Top–

Using this technique with ZenPhoto and other CMS systems

The basic principles are the same no matter what system you use. The only challenges are (1) how self-contained plug-ins are (if they frequently look for files outside of the plugins folder, then there is a high chance it won’t work), and (2) how spread-out the files are (the more spread out, the more symlinks you have to create and maintain).

With ZenPhoto, I wanted to add my own CSS file to the default theme. I had to symlink directly to my new CSS file (same process, except you enter the full path and filename, not just the pathname) from within the styles directory of the theme. Again, it’s the same philosophy, but a little more work. But, when I make a change in that one style sheet, the three sites that share that sheet are all updated instantly. Very cool.

–Top–

Additional resources

Articles:

• “Symbolic link.” Wikipedia, The Free Encyclopedia. 6 Mar 2008, 18:31 UTC. Wikimedia Foundation, Inc. 10 Mar 2008 <http://en.wikipedia.org/w/index.php?title=Symbolic_link&oldid=196335114>.

Content management systems:

• WordPress is a state-of-the-art semantic personal publishing platform with a focus on aesthetics, web standards, and usability
• ZenPhoto, a simpler web photo gallery

Software tools:

• FileZilla, the free FTP client
• PuTTY: a free telnet/ssh client

Service providers:

• DreamHost Internet service provider
• Sacramento Online Services for sensible domain name and e-mail prices

–Top–

Comments and feedback

I would appreciate any feedback that you might have. If I left any steps out, or if I could have explained something more clearly, please let me know.

If you use the technique, please leave me a comment. You are also welcome to link to one of your sites that use it.

If you are a plug-in author who has updated your plug-in to work more gracefully with this technique, please let us know!

–Top–