Textpattern multisite setup

Overview

Textpattern version 4.2.0 introduced an option for running multiple sites off a single installation. It’s fussier than a standard installation, though, with an additional requirement (symbolic links) that some low-budget shared hosting won’t support.

The multisite configuration allows using different domains for the public and admin sides of a site. This keeps sensitive files out of the public side, and allows secure admin login if you’re set up for SSL. There is also some advantage to having a single set of core files to maintain and upgrade, but this cuts both ways — you must upgrade all the sites at the same time, like it or not.

Here are the steps I took to convert a group of existing sites to multisite, first on an OS X development box, then on a Dreamhost shared hosting account. While the README.txt file included in the sites directory got me most of the way there, I found a few details and pitfalls it didn’t cover.

Goals

• Use the “recommended” configuration, with the admin side in its own subdomain
• Use the same configuration on development and live servers
• Transfer live sites with no appreciable downtime

Creating the configuration on the development server

Even though my goal was to convert existing sites, I thought it would be simpler to start by creating a fresh Textpattern site in the multisite configuration. That would allow me to get the configuration right without worrying about any site-specific issues.

• Unpack a fresh Textpattern 4.2.0 directory.
• Create a virtual host for the admin side and point it to sites/site1/admin in the new installation. I’ll call it admin.site1.dev.
• Create another virtual host for the public side, pointing to sites/site1/public.
• Restart the web server.
• Create a new database.
• Browse to admin.site1.dev/setup.
• On the MySQL/URL screen, you’ll have to enter the correct public URL.
• When creating config.php, you must add define('txpath', $txpcfg['txpath']); just before the closing ?> tag (actually you could delete this tag).

So far so good; all of this is clearly outlined in sites/README.txt. You can now log in to the admin side of the new site. (There is the expected version 4.2.0 bug where your first login doesn’t quite work and you have to log out and back in again.) If your normal habit is to go straight to Diagnostics, you’ll find the usual warning about deleting the setup directory. You’ll also see Site URL preference might be incorrect, and you’ll have to live with this one, because this test doesn’t understand multisite.

More significantly, you will get a Clean URL test failed warning. This is pitfall #1. Each public directory in a multisite installation needs a copy of the top-level .htaccess file, but this isn’t included in the current build, nor does sites/README.txt tell you this. So copy or move the file (it isn’t needed in the root directory), or make a symlink to it. The symlink option is great if all the sites in this installation have the same .htaccess requirements.

Adding .htaccess only seems to make things worse, though; I now get clean_url_data_failed: <br />. Visiting the public side of the new site confirms that there is indeed something wrong: the site is there, but there are various PHP warnings and notices. This is pitfall #2: there are two serious errors in sites/site1/public/index.php. This has been fixed in the development version of the file, so grab the newer version and swap it in.

Now the site should be working correctly. Follow Step 3 in sites/README.txt to secure the installation. Note that removing the top-level index.php, as suggested, results in a Missing files warning; as with the Site URL preference might be incorrect warning you can ignore it. Also, some of the links in the Welcome to Your Site! article will be broken, because they assume a standard installation.

Transferring an existing site on the development server

• Copy the sites/site1 directory, using cp -R to keep all the symlinks working. I’ll name the copy example.dev.
• Edit example.dev/private/config.php with the correct database settings.
• Create a virtual host for the admin side and point it to example.dev/admin. Presumably you already have a virtual host for the public side; redirect it to example.dev/public. Restart the web server.
• Copy the images and files directories from the original site to example.dev/public, along with any other directories you may have added (e.g. css or js directories).
• Log in to the new site. Edit the following preference settings:
  • siteurl
  • file_base_path
  • tmp_dir

path_to_site also needs to be changed, but that should happen automatically. However, there’s no harm in changing it yourself. It’s a hidden preference so you’ll have to do this directly in the database (or with smd_prefalizer).

If you have any public-side links to /textpattern/jquery.js you’ll have to fix those. Add a copy of (or symlink to) jquery.js to the public side and point your links there instead.

Check over the site (and Diagnostics, of course) to make sure everything is working correctly. Make notes on any any changes you have to make, because these will have to be transferred to the live site.

Transfer the remaining sites in the same way.

Transferring the new configuration to the live server

Again, the goal is minimal downtime. This means retaining the ability to revert very quickly to the old configuration if the new one has problems. This entails extra steps but I found the peace of mind well worth it.

Transfer the files

I simply uploaded the entire directory tree of my new multisite setup to the root level of my Dreamhost account. I used a desktop SFTP client; the smart thing would have been to use rsync -l, which would have preserved all the symlinks. But I haven’t used rsync before and it didn’t occur to me at the time. It was easy enough to recreate the symlinks.

Create new admin subdomains

Do this now because sometimes it takes a few hours for a new subdomain to come online. Point the new subdomains to the appropriate admin directories in the multisite setup.

Clone the databases

I then created a new database for each site, cloning the existing database by doing a complete mysqldump and uploading that into the new database. I then directly edited each new database in Sequel Pro, changing the four preference settings listed above. This was not strictly necessary but was part of my zero-downtime plan. The main thing to catch now is path_to_site, because this is a hidden preference. It may not matter; Textpattern has various checks and will auto-update it, but I’m not sure that it will do this with zero glitches on the public side. The other three preferences you can change in the admin panel if you prefer.

Log in

Do the usual Diagnostics checks. If you had any issues getting sites working correctly on the development server, duplicate any needed changes now.

I added a comment (<!-- test -->) to an obvious spot in the homepage template of the multisite version of the site, so that I could easily confirm that the transfer was successful.

Redirect the public-side domains to the new installation

In the Dreamhost web panel, go to Domains->Manage Domains. For the first site, click its Edit link, then update the Web Directory setting to point to the appropriate public directory in your multisite tree. Now hurry to the public side and check the HTML source and look for the <!-- test --> comment. It might take a minute or two for the domain web directory change to go through. Once you see it, go through the site to confirm that everything is working correctly.

If you see significant problems you can redirect the public-side domain back to the original site while you decide how to deal with the issues. But for me the transition was seamless.

Repeat with the remaining sites.

When you’re happy with the results, you can trash the old site files and databases.

Note: Draft article preview broken

Putting the admin site into its own subdomain breaks the draft article preview feature. It’s a pretty simple issue so hopefully this will be fixed in the next Textpattern release.

Posted 2010-02-21 (last modified 2010-03-04)