=================================
= Textpattern Multi-Site How-to =
= =
= Author: Sam Weiss (artagesw) =
=================================
=========================
= Contents of Directory =
=========================
This directory (sites) is optional. If you do not wish to host multiple
Textpattern sites from a single Textpattern installation, you may remove this
directory with no ill effects.
This directory may be used to create multiple Textpattern-based sites from a
single installation of Textpattern. With a multi-site setup, you may host
multiple Textpattern sites while having only a single copy of the Textpattern
core code to maintain and update.
In a fresh installation, the sites directory will contain a single subdirectory
named site1. You may rename the site1 directory to whatever you like.
For example:
subdomain.example.com
You may treat the site1 directory as a template for creating new Textpattern
sites. Simply duplicate the entire site1 directory to a new directory (within
the sites directory) with a name appropriate for your new site. For example:
cp -R site1 site2
IMPORTANT! Be sure to designate the "-R" option to cp so that symbolic links
are maintained.
============
= Overview =
============
Textpattern 4.2 introduces new multi-site capabilities. You may take advantage
of these capabilities to:
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.
For example, you might have the following Textpattern-driven sites, all running
off a single shared installation of the Textpattern code:
http://www.example.com
http://admin.example.com
http://www.example.net
https://admin.example.net
http://www.example.org
https://admin.example.org
========================================
= How to Set up Textpattern Multi-Site =
========================================
The following sections describe how to set up multiple Textpattern sites from a
single installation. There are two slightly different sets of instructions,
depending upon whether you prefer to:
A. Create separate subdomains for your Textpattern admin areas (recommended), or
B. Allow access to the admin area through a subdirectory of your site (the
traditional setup).
==========================================
= A. Multi-Site with Separate Admin Area =
==========================================
This setup method results in separate subdomains for your Textpattern-powered
site and its associated admin area. For example:
http://www.example.com <-- URL to your site
http://admin.example.com <-- URL to your site's admin area login
https://admin.example.com <-- URL to your site's secure admin area login
----------------------------
Step 1: Configure Web Server
----------------------------
In order to separate the admin area into its own subdomain, you will need to use
your web host's facilities to create two virtual hosts per Textpattern site. One
virtual host will be used to access the Textpattern admin area, and the other
will be used to access the Textpattern-powered site. This configuration step is
commonly performed via your host's web panel.
You need to set the document root of the admin virtual host to the admin
subdirectory of your site. Set the document root of the site virtual host to the
public subdirectory of your site. Also, be sure that the virtual host allows
traversing symbolic links.
Here is an example config for Apache to create our virtual hosts for site1:
<VirtualHost *:80>
ServerName example.com
ServerAlias www.example.com
DocumentRoot "/path/to/textpattern/sites/site1/public"
<Directory "/path/to/textpattern/sites/">
Options +FollowSymLinks
</Directory>
</VirtualHost>
<VirtualHost *:80>
ServerName admin.example.com
DocumentRoot "/path/to/textpattern/sites/site1/admin"
<Directory "/path/to/textpattern/sites/">
Options +FollowSymLinks
</Directory>
</VirtualHost>
You may need to restart your web server before it will recognize new virtual
hosts. Create a pair of virtual host configurations for each Textpattern site
you will be hosting.
-------------------------
Step 2: Textpattern Setup
-------------------------
You should now be able to proceed through Textpattern's setup process.
* If you set up your admin area on SSL, go to:
https://admin.example.com/setup
Otherwise, go to:
http://admin.example.com/setup
* On MySQL setup page, be sure to enter the correct URL to your Textpattern site
(not the admin site) under Site URL. Textpattern will default to the URL of
your admin site and you will need to change that here. For example:
www.example.com
* Textpattern will tell you to place your config.php file in /textpattern/.
This is INCORRECT. Place it in the private subdirectory of your site.
For example:
/sites/site1/private/config.php
* IMPORTANT! When you create your config.php file, be sure to add the following
line just before the closing '?>' tag:
define('txpath', $txpcfg['txpath']);
-------------------------------
Step 3: Secure the Installation
-------------------------------
For security reasons, you should remove the Setup directory once the setup has
been completed. Remove both of the following:
sites/site1/admin/setup
sites/site1/public/setup
--
The site1 template includes a symbolic link to the admin directory inside the
public directory. This is only used for the alternate setup described below
("Multi-Site with Integrated Admin Area"). Since we will be accessing the admin
area from a separate subdomain, this symbolic link is not necessary and should
be removed.
Remove the following:
sites/site1/public/admin
--
Once setup is complete, access to the theme directory is no longer needed from
the public side.
Remove the following:
sites/site1/public/theme
--
You may also want to remove the following files and directories from the
top-level Textpattern directory, as they are not needed when running multi-site:
files
images
index.php
---------------------------
Step 4: There is no Step 4!
---------------------------
But if you want to to set up additional sites, simply repeat steps 1 through 3
for each site. Your sites directory layout will look like the following:
sites/
example.com/
admin/
private/
public/
example.net/
admin/
private/
public/
example.org/
admin/
private/
public/
============================================
= B. Multi-Site with Integrated Admin Area =
============================================
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.example.com <-- URL to your site
http://www.example.com/admin <-- URL to your site's admin area login
----------------------------
Step 1: Configure Web Server
----------------------------
You will need to use your web host's facilities to create a single virtual host
for each of your Textpattern sites. This configuration step is commonly
performed via your host's web panel.
Set the document root of the site virtual host to the public subdirectory of
your site. Also, be sure that the virtual host allows traversing symbolic links.
Here is an example config for Apache to create our virtual host for site1:
<VirtualHost *:80>
ServerName example.com
ServerAlias www.example.com
DocumentRoot "/path/to/textpattern/sites/site1/public"
<Directory "/path/to/textpattern/sites/">
Options +FollowSymLinks
</Directory>
</VirtualHost>
You may need to restart your web server before it will recognize new virtual
hosts. Create a single virtual host configuration for each Textpattern site you
will be hosting.
-------------------------
Step 2: Textpattern Setup
-------------------------
You should now be able to proceed through Textpattern's setup process.
* Go to: http://example.com and click the textpattern/setup/ link.
* Textpattern will tell you to place your config.php file in /textpattern/.
This is INCORRECT. Place it in the private subdirectory of your site.
For example:
/sites/site1/private/config.php.
* IMPORTANT! When you create your config.php file, be sure to add the following
line just before the closing '?>' tag:
define('txpath', $txpcfg['txpath']);
* Once Textpattern creates your site's database tables, it will present a link
to the "main interface." This link will be INCORRECT, so do not click it.
Instead, manually enter the address of your admin area into your browser's
address bar at this point:
http://example.com/admin
-------------------------------
Step 3: Secure the Installation
-------------------------------
For security reasons, you should remove the Setup directory once setup has
completed.
Remove both of the following:
sites/site1/admin/setup
sites/site1/public/setup
--
Once setup is complete, access to the theme directory is no longer needed from
the public side.
Remove the following:
sites/site1/public/theme
--
You may also want to remove the following files and directories from the
top-level Textpattern directory, as they are not needed when running multi-site:
files
images
index.php
---------------------------
Step 4: There is no Step 4!
---------------------------
But if you want to to set up additional sites, simply repeat steps 1 through 3
for each site. Your sites directory layout will look like the following:
sites/
example.com/
admin/
private/
public/
example.net/
admin/
private/
public/
example.org/
admin/
private/
public/
=========================
= Additional Miscellany =
=========================
The default article that is displayed after a clean installation will have some
broken links. This is to be expected, as the links are hard-coded to the
traditional /textpattern/ back-end.