WakkaWiki Setup Documentation

The following is a step by step overview of the process involved in creating the TeacherResourceWiki, an implementation of the WakkaWiki engine.

Choosing a Wiki Engine

There are many different wiki engines which provide many of the same functions, though each engine seems to have its own set of unique features. If you are unsure about what engine you would like to use, you may wish to peruse the exhaustive list of wiki engines to help make your choice. This documentation will continue with the assumption that you have chosen to use the WakkaWiki engine.

Reasoning behind choosing the WakkaWiki engine includes the ability for the wiki to comply to established web standards by outputting valid XHTML and CSS, as well as the ability to subscribe to topics/pages or the entire site via an RSS feed.

Prerequisites

In order to utilize the WakkaWiki engine, you will need to have access to a web server equipped with:

Although it is beyond the scope of this tutorial/documentation to describe the installation of either PHP or MySQL, if you pay for hosting with any major web server provider, you should have access to both of these. If you happen to be at a school/job where you host your own web server and are lucky enough to do so on a Mac OS X machine, you can check out these docs on installing PHP (if it is not already present) and installing MySQL quite easily on your Mac.

MySQL setup

Assuming that you now have access to a server running PHP and MySQL, our first step will be to set up access to a MySQL database. This can be done either using a web-based MySQL helper application (such as the one found in cpanel, a web-based control panel often used by webhosting providers) or by inputting direct commands into the MySQL application. Note that here we will describe the process when using cpanel to create a new MySQL database and user. If you do not have access to a tool such as cpanel and must add a database and user manually, see the installation guide at WakkaWiki, step two.

Our first step will be to create the MySQL database that will hold the wiki data. An appropriate name may simply be "wakka" or "wiki", though for this example, we will use "wikiTest". To create this database in cpanel, simply click on the "MySQL Databases" tab on the left hand side of the screen, and then on the "Manage Databases" link:

Image of which tab to select in cpanel.

Now scroll down to the end of the Databases section, to where there is an input box titled Db:, and type in the name of the database:

Image of the Db: input box.

We now need to add a user to this database, so we scroll down a little further until we get to the Users section, and enter in a username and password. For this example, I have been incredibly creative and called our user "wikiTest" with a password of "someSecret". Note that the database, username and password are case-sensitive!

Image of creating the database user.

Finally, we need to give the user "wikiTest" access to the database "wikiTest" that we have created. To do this, scroll back up to the bottom of the Databases section, where we created and named the database earlier. From the pop-up menu, select the user name ("educati_wikiTest" in this case) and database ("educati_wikiTest" in this case) and click on the "Add User to Db" button.

Adding the user to the database image.

Note that cpanel has changed the name of our user and database by prefacing them with the word educati_. If your host does a similar thing, remember to include the FULL name (with the preface) when telling WakkaWiki your configuration later on.

WakkaWiki directory preparation

First things first: many of the steps that are described below could be completed either through an FTP client or through the cpanel interface. For the purposes of this documentation, we will use the cpanel interface for all but one step. If you prefer to use an ftp client to perform these steps, feel free.

You must now decide upon where your wiki is going to live, and create the directory accordingly. I have created a directory called "wikiTest" for this tutorial through cpanel. First, select the "Site Management" tab on the left hand side of the screen, and then choosing the "File Manager" link.

File Manager image.

Note that to get around the File Manager interface in cpanel, you must click on the icons to move to that location, or the text to perform an action on the file or folder.

To create the new directory, first make sure you are in public_html (or your equivalent thereof, where public_html signifies that its subdirectories are accessible via the web) and then click on the "Create New Folder" link, and enter the name of your new directory into the box on the right hand side of the screen. Now navigate into the directory that your just created by clicking on its folder icon.

Within our new directory, we must now create a file called ".htaccess" with the following data in it:

RewriteEngine on
RewriteRule ^style/logo/r=(.*)/g=(.*)/b=(.*)/(.*)$ style/betapilogo.php?r=$1&g=$2&b=$3 [QSA,L]
RewriteRule ^style/logo/grey=(.*)/(.*)$ style/betapilogo.php?grey=$1 [QSA,L]
RewriteRule ^style/(.*)$ style/$1 [L]
RewriteRule ^style$ wakka.php?wakka= [L]
RewriteRule ^(.*)$ wakka.php?wakka=$1 [QSA,L]

To accomplish this in cpanel, click on the create new file button, and create a text document entitled ".htaccess" (don't forget the period at the beginning).

Creating the .htaccess file.

Now click on the file .htaccess and then click on the "Edit File" link. A new window will open, within which you should copy and paste the data listed above, and then click the "Save" button.

We must also create another text file entitled "wakka.config.php" and set the permissions to 666. To do this, click on the create new file button again, and call it "wakka.config.php". Now click on the "wakka.config.php" file, and then on "Change Permissions". Set the permissions to 666:

chmod 666 for the file wakka.config.php

Now, on to the getting the actual engine going!

Download the engine

Head on over to the WakkaWiki download page and pick up the latest release of the engine (0.1.2 when this was written on May 17, 2004). If you are unfamiliar with the extensions that you see on the release (namely .tar.gz), don't worry about it. It just means that the folder is compressed as something called a tarball and then gzipped. If you open the file you just downloaded with something like Stuffit Expander (free for either Mac or Windows) or the commercial WinZip, it will be able to decompress it without a problem. Do this, if your browser did not automatically decompress it for you already. You should end up with a folder called "wakka-0.1.2" (the version numbers at the end may differ with a future release).

The next step will be to transfer the contents of the folder you just downloaded into the directory that we have prepared for the wiki (the one where we created the .htaccess file and the wakka.config.php file. To do this, you should use an ftp client such as Cyberduck (Mac OS X) or SmartFTP (Windows), or whatever ftp client you already have. Connect to your domain using your username and password (the same username and password that you use to access cpanel, NOT the MySQL username and password that you just created) and navigate to the directory within which the WakkaWiki is going to live. Now, select all of the contents of the "wakka-0.1.2" folder, and transfer everything into the directory you have navigated to with your ftp client.

Final Configuration

Now, using your web browser, head over to the URL where your wiki lives. For example, I created my directory "wikiTest" in /public_html/wikiTest so I will go to http://www.educationaltechnology.ca/wikiTest/

Note that the trailing slash is required. If anyone can figure out how to make the rewrite rules for the .htaccess file listed above work properly AND map /wikiTest to /wikiTest/, please let me know...

You will now be presented with some configuration options by WakkaWiki, part of which is entering in your MySQL username and password that you created earlier. Remember to include any prefix that your webhost adds to your MySQL users and databases, and that this information is case-sensitive:

Configure your WakkaWiki installation with the MySQL information you created earlier.

Fill out the rest of the information, and make sure that when you set the Base URL, it should end with a trailing slash (ie. no index.html or anything like that after it). This is important! If this base URL is incorrect, you will have to go in and muck about with the settings by hand in the wakka.config.php file.

Setting the base URL properly (no index.html)

There should be 3 steps to this configuration process, though you only need to fill out information on the first one. After the final step is completed, you need to change the permissions of the wakka.config.php file back to 644. To do this in cpanel, follow the same instructions as given above for setting the permissions to 666, but simply remove write access for Group and World:

chmod 644 for the wakka.config.php file

Congratulations! You should now have a working copy of WakkaWiki!

Questions/Problems

If you have difficulty with the installation, you might find it useful to browse through the official WakkaWiki installation documentation. Good luck!