Advanced Guide to Installing Multiple MediaWiki Sites

From DFWLPiki
Jump to: navigation, search

Scope of This Document

In this article, we will explore how to have but one actual installation of the port www/mediawiki, but with the outcome of being able to support two or more wiki sites. This eample is written for FreeBSD, but the theory still applies to any of the other various unices as well.

Prerequisites to Begin This Exercise

1) An updated FreeBSD server
2) Apache 2.2.x installed with PHP5 (and check to build the Apache module)
3) MySQL 5.0.x installed
With the above, I'll assume you followed my Installing FreeBSD 6.2 article, using the minimal install method. Also, everything is installed using the ports collection. I also assume you know how to pull down the ports tree using your favorite method (I prefer csup). Many of these aspects of FreeBSD system administration are outside the scope of this article.

Some other things to keep in mind: First, we will have our test server, and lets say its name is "". In the end, we will have built 3 sites, "", "", and "". Where appropriate, don't forget to substitute in the proper name of your server, as well as names you choose for your wikisites (you don't have to use the same names as I do, if you don't want!).

Getting Started

The default install of MediaWiki from ports, will put the mediawiki directory in /usr/local/www/. What we will end up with when we are done here, is multiple wiki sites that feed off the main MediaWiki install location. Each wiki site will get its only folder, but nearly all of its contents will be symlinks back into /usr/local/www/mediawiki. Sound simple? Actually... it is! Lets get started!

Configuring the Database Server

Since MySQL 5.0.x is already installed, check your /etc/rc.conf to make sure it will start when the server starts. You will need a line like this, and if its not there already, add it.


Make sure its MySQL is started:

/usr/local/etc/rc.d/mysql-server status

If it says 'not running', then start it like this:

/usr/local/etc/rc.d/mysql-server start

Now we're ready to move on to installing MediaWiki.

Installing MediaWiki

Installation will be pretty straight forward. We are going to do www/mediawiki, and graphics/ImageMagick.

cd /usr/ports/www/mediawiki; make BATCH=yes install clean
cd /usr/ports/graphics/ImageMagick; make BATCH=yes install clean

That will probably run for a bit, but it shouldn't take too terribly long. Even though this is not covered on this document, remember that PHP5 with apache support is required. If you need help with this, see my document titled Deploying a FreeBSD 6.2 Server.

Configuring Apache 2.2

We will not be configuring a site for /usr/local/www/mediawiki as we normally would, for a single site installation. Instead, we will create some folders to hold our example wikis, and then well configure these to be accessed by Apache. Time to create the folders for our wiki sites:

cd /usr/local/www/
mkdir wikisite1 wikisite2 wikisite3

Now, we need to add some configuration to our Apache so that these folders can be used as sites. If you followed my Deploying a FreeBSD 6.2 Server guide, then along the way you would have created and used the file /usr/local/etc/apache22/Includes/httpd-local.conf. This is what we're going to add to that file now:

#Directories for Test Wikis
<Directory /usr/local/www/wikisite1>
   AllowOverride None
   Order Allow,deny
   Allow from all
<Directory /usr/local/www/wikisite2>
   AllowOverride None
   Order Allow,deny
   Allow from all
<Directory /usr/local/www/wikisite3>
   AllowOverride None
   Order Allow,deny
   Allow from all
# Virtual Hosts
NameVirtualHost *:80
# VH for
<VirtualHost *:80>
   DocumentRoot /usr/local/www/apache22/data/
   ErrorLog /var/log/httpd/error.log
   CustomLog /var/log/httpd/webhost.domain.com_log combined
# VH for
<VirtualHost *:80>
   DocumentRoot /usr/local/www/wikisite1
   ErrorLog /var/log/httpd/error.log
   CustomLog /var/log/httpd/wikisite1_log combined
# VH for
<VirtualHost *:80>
   DocumentRoot /usr/local/www/wikisite2
   ErrorLog /var/log/httpd/error.log
   CustomLog /var/log/httpd/wikisite2_log combined
# VH for
<VirtualHost *:80>
   DocumentRoot /usr/local/www/wikisite3
   ErrorLog /var/log/httpd/error.log
   CustomLog /var/log/httpd/wikisite3_log combined

What we have above, is three sets of Directory statements (which allow Apache to serve files that are out of the DocumentRoot, and then four Virtual Host setups that will serve files based on three virtual names that are not really the name of our server (don't forget, now that were using Virtual Hosts in our Apache configuration, we have to have a virtual host for our actual webhosts directory).

Our log files go in a directory by themselves, and if we don't create it, Apache won't start.

mkdir /var/log/httpd

For purposes of making this all work without reconfiguring our local DNS server, lets add some statements to our local systems /etc/hosts file. One line for each virtual host wikisite, and each one points to the same IP address of the host. Basically, you cause all these names to go to one place. wikisite1 wikisite2 wikisite3

You can even add a fourth line if you need to, so you can resolve your host if you need to: webhost

Make sure Apache is listed in the /etc/rc.conf, and then make sure its started. If you need to, add this line to /etc/rc.conf:


Then, check to make sure its started. If it's not, start it.

/usr/local/etc/rc.d/apache22 status
/usr/local/etc/rc.d/apache22 start

If you want to, you can test that these are working by pinging each one by long FQDN or shortnames. If that is working, you can also test by putting each of those names into your browser as a URL. The URL should return a test page that says "It Works!", but the other 3 sites should just turn up empty web directories.

Creating the MySQL Databases

Our databases have to have a user that the system uses for access. I'm just going to create three accounts named wiki1, wiki2, and wiki3. Each one will have their shell specified as 'nologin' and their homedir as '/nonexistant'. I also gave them passwords like 'wiki1wiki1', and so forth. After those are created, you're ready to move on.

Creating the actual databases is not that hard, even if you don't know anything about MySQL (like me!). In this next set of commands, we will create the databases, and then assign each one with the proper permissions for its database user.

mysqladmin --user=root create wikisite1
mysqladmin --user=root create wikisite2
mysqladmin --user=root create wikisite3
echo "GRANT ALL ON wikisite1.* TO wiki1@localhost IDENTIFIED BY 'wiki1wiki1'; FLUSH PRIVILEGES;" | mysql
echo "GRANT ALL ON wikisite2.* TO wiki2@localhost IDENTIFIED BY 'wiki2wiki2'; FLUSH PRIVILEGES;" | mysql
echo "GRANT ALL ON wikisite3.* TO wiki3@localhost IDENTIFIED BY 'wiki3wiki3'; FLUSH PRIVILEGES;" | mysql

Symlinking the Master MediaWiki Directory

So remember, that our www/mediawiki installed to /usr/local/www/mediawiki, and that we created 3 other directories wikisite1, wikisite2, and wikisite3 in /usr/local/www/. Now, its time to link these 4 items together. Here is how the process goes:

cd /usr/local/www/wikisite1/
ln -s /usr/local/www/mediawiki/* .
rm -rf config
cp -vpnRP ../mediawiki/config .
rm -rf images
cp -vpnRP ../mediawiki/images .

BE CAREFUL when you 'rm -rf config', make sure that you DO NOT put a trailling slash on config and images. If you do, you will delete the one at the end of the symlink!! Also, BE CAREFUL when you 'cp -vpnRP' the config and images directory over, that you DO NOT add a trailing slash to the ../mediawiki/config. If you ../mediawiki/config/ you will copy the contents of ../mediawiki/config, not the actual folder. Now that you have carefully completed those tasks, if you 'ls -G', you should see a bunch of purple links, with two blue folders.

Time to Set Up the Wiki Sites

Ok, moment of truth time. If you did all of the previous configuration correctly, then you should still be getting the "It Works!" page at your webhost's URL, and if you go to, you should see the start page of the MediaWiki configuration. It should say:

MediaWiki 1.10.0
Please set up the wiki first.

Click the link. For the purposes of this test, I am going to name each site accoring do its URL. The blanks that are listed with red text next to them are the ones you need to pay the most attention to. For "Wiki name:", I put WikiSite1. "WikiSysOp", I left that name there, and put a password in. You will need to remember this password for later when you are ready to log in and make edits. Strictly for this documentation, I am going to use 'wiki1wiki1', but I highly suggest you use something that only you know.

Skip down now to the "Database Config" section, and 'Database name:', put "wikisite1". Username is wiki1, and the password is 'wiki1wiki1'. That's it! Scroll down, and hit the "Install Mediawiki" button! You should see some scrolling, and the last line should say:

Creating LocalSettings.php...
Installation successful! Move the config/LocalSettings.php file into the parent directory, then follow this link to your wiki.

Move the config/LocalSettings.php to /usr/local/www/wikisite1/, and click the link!!

mv /usr/local/www/wikisite1/config/LocalSettings.php /usr/local/www/wikisite1/

Welcome to your MediaWiki!!! Repeat the above steps starting at "Symlinking the Master MediaWiki Directory" for wikisite2 and wikisite3, and you will have 3 fully functioning MediaWiki sites, each with their own separate MySQL database. You can add more at any time too.

The Method Behind The Madness

So what's the point of all this configuration of a dummy mediawiki site, and then using separate directories for for each wiki? Well, it all boils down to one thing, and one thing only. Updates!! One of the beautiful things about FreeBSD, is the ports system. The easiest way IMO to keep every thing on your system updated, is to use 'portupgrade -a', and just let it run until everything is updated. It's an entirely automatic process. But, since the default install of www/mediawiki installs to /usr/local/www/mediawiki, how do you then install a second MediaWiki, but still have it automatically updated by portupgrade? Well, with the formula above... that's how!

The only thing to keep in mind, (and I'm not sure that I would even consider this a caveat), would be that that after a portupgrade of MediaWiki, it would be wise to cd into each../[wikisite]/maintenance/, and run your update.php script. This script uses configurations from each site's LocalSettings.php file, and makes the necessary updates in the MySQL database. If there are any incompatibilities between previous versions and a new version, this update.php file is what takes care of how all the various .php files of MediaWiki read data from the database. As long as each site promptly has update.php run against its own LocalSettings.php, there shouldn't ever be any problems.