One of the new features for Textpattern 4.2.0 is the multi-sites file system layout. What this means is that you can now have one Textpattern install controlling many sites. Instead of upgrading many sites, you only need to upgrade the one install.

Note that each site will still be separate and your pages, forms and styles will not be shared between installs – only the base installation of Textpattern is shared. As usual you will have a separate Admin for each site.

This tutorial

This tutorial is mainly aimed at installing multi-sites on Joyent but the instructions may be helpful for other web server installations. I used the following guidelines for setting up multi-sites on TXP Tips. Note that I used Coda’s in built Terminal for shell access – use whichever application works for you.

Advantages of a multi-site system layout

1. Create multiple Textpattern-driven web sites from a single installation of the Textpattern core code base
2. Separate the Textpattern admin area from the Textpattern-driven web site by placing it into its own web root and subdomain
3. Gain a modicum of extra security by removing the vast majority of the Textpattern core code from the web document root
4. Easily protect the admin area via SSL, if you place it into its own web root and subdomain

The multi-sites feature is very powerful, and allows for two basic setup methods:

• A. Multi-Site with Separate Admin Area
• B. Multi-Site with Integrated Admin Area

Option A

This setup method results in separate subdomains for your Textpattern-powered site and its associated admin area. For example:

http://www.mysite.com         <-- URL to your site
http://admin.mysite.com       <-- URL to your site's admin area login

Option B

This setup method results in the more traditional Textpattern installation, where the admin area is located in a subdirectory of the main site’s domain. For example:

http://www.mysite.com         <-- URL to your site
http://www.mysite.com/admin   <-- URL to your site's admin area login

Installing multi-sites on your server

On many hosts, all you need to do is follow the instructions provided in the readme.txt file within the textpattern-4.2.0/sites/ folder of a default Textpattern 4.2.0 install.

Installing multi-sites on Joyent

In the case of TXP Tips, which is hosted by Joyent, the default method outlined in the readme.txt does not work.

Sam Weiss, the Textpattern developer who created the multi-sites feature, has a Multi-sites install script for Joyent that automates the multi-site setup on Joyent servers. For shared hosts that impose a domain directory structure (Joyent shared hosting falls into this category), you cannot use the included sites directory. Instead, you must create your own.

What the script does

The script should not overwrite directories that already exist. The default settings are for Joyent, so it tries to create:

web/
   admin/
   public/
   private/

If the site already exists, web/public will already be there, so the script should not overwrite it.

Getting started with a clean install

1. Upload the txp_create_site.sh script to your server in the root: /users/home/yournamehere/
2. I set the permissions on the script to 700
3. Read the readme.txt thoroughly
4. Open a shell window – I used Coda’s Terminal
5. In the Terminal window go to your domain – $ cd /users/home/yourusername/ or $ cd /users/home/yourusername/domain/yourdomain.com
6. Run the txp_create_site.sh script with txp_create_site.sh or ~/txp_create_site.sh depending on if you are in the main domain or a sub-domain
7. You should now have a new /web directory. Enter either cd ~/web or cd ~/domains/yourdomain.com/web in Terminal, depending on whether you are in the main domain or a sub-domain
8. Run the following command in Terminal to download Textpattern 4.2.0 – but be sure to change the path and domain name as necessary

cd ~/domains/txptips.com/web
wget http://textpattern.com/file_download/56/textpattern-4.2.0.tar.gz
tar xzf textpattern-4.2.0.tar.gz
rm textpattern-4.2.0.tar.gz
ln -s textpattern-4.2.0 textpattern

The script creates a config-dist.php file in your site’s private directory that is preconfigured. Simply copy that file and edit the appropriate lines as instructed by the textpattern setup process. Again, change the path if necessary.

cd web/private
cp config-dist.php config.php
nano -w config.php

You are nearly done. Update your “File directory path” and “Temporary directory path” settings in Advanced Preferences. These will default to directories inside the shared textpattern directory. You want to change them to (for example):

/users/home/{username}/domains/{mydomain.com}/web/public/files
/users/home/{username}/domains/{mydomain.com}/web/public/tmp

Upgrading existing sites

If you are upgrading an already existing site, some slightly different steps are required:

1. Rename your /web directory to, for example, web.orig
2. Open a shell window in Terminal
3. Navigate to the directory where you will run the script cd ~/domains/txptips.com – change the path as necessary
4. Run the script – I used ~/txp_create_site.sh ~/web/textpattern because multi-sites had already been installed in the root directory and we need to point the script at the main domain Textpattern install (if it already exists, if not, follow the next step)
5. If Textpattern has already been installed, move onto the next step (copy assets) because you only require one Textpattern install for multi-sites. Otherwise, run the following command in Terminal to download Textpattern 4.2.0 – but be sure to change the path and domain name as necessary.

cd ~/domains/txptips.com/web
wget http://textpattern.com/file_download/56/textpattern-4.2.0.tar.gz
tar xzf textpattern-4.2.0.tar.gz
rm textpattern-4.2.0.tar.gz
ln -s textpattern-4.2.0 textpattern

1. Copy your static assets (images, files, etc.) from web.orig/public/ to the new web/public/
2. The script creates a config-dist.php file in your site’s private directory that is preconfigured. You can copy the file and change the name to config.php
3. Update the “File directory path” and “Temporary directory path” settings in your Advanced Preferences. These will default to directories inside the shared textpattern directory. You want to change them to (for example):

/users/home/{username}/domains/{mydomain.com}/web/public/files
/users/home/{username}/domains/{mydomain.com}/web/public/tmp

Your site will be down for a short while during the transition.

Run the script in each domain

By default, Joyent has a domain directory structure like so:

/users/home/yournamehere/web/public   <-- the root domain
/users/home/yournamehere/domains/yourdomain.com/web/public   <-- your secondary domains

On Joyent, you will need to run the script on each sub-domain if you wish to run multi-sites on all your domains. Your Textpattern install is shared by all domains through the symlinks created by the script.

Install Textpattern only once

Again, please note that Textpattern itself only needs to be installed once, either in your main domain as in my case or in a sub-domain.

For more information or help with this script, please visit the forum thread.