Toolserver/Other

Toolserver

This box: view · talk · edit

Create an example project

Structure

This section will explain how to set up an example PHP project on the toolserver. This assumes that you know PHP. Writing scripts in other languages requires the use of the public_html/cgi-bin directory and a good understanding of CGI programming. Note: the toolserver is not designed for running test projects and debugging them by trial and error. This section will explain how to test your projects locally before uploading them to the toolserver.

Let's start by designing the structure of our sample project. Our project's main page is index.php, which is placed in public_html folder. We are going to connect to a database, so we need to use a database user name and password. For security reasons, it is not a good idea to store the username and password in index.php file because it is accessible from the Internet. Instead, we are going to add a file named database.inc to our home directory (the directory which is the parent of public_html directory) and reference it in our index.php file.

For the purpose of this tutorial, suppose that the user name of the person who is setting up this sample project is clarke. Clarke might start by creating a PHP file (named index.php) on the desktop of his computer. This is the code of that file:

<?php
require_once('../database.inc');
mysql_connect('enwiki-p.db.toolserver.org', $toolserver_username, $toolserver_password);
@mysql_select_db('enwiki_p') or die(mysql_error());
$query = "SELECT MAX(rev_id) AS max_rev_id FROM revision";
$result = mysql_query($query);

if(!$result) die("ERROR: No result returned.");

while($row = mysql_fetch_assoc($result))
{
    echo "The highest value of rev id is: {$row['max_rev_id']}.";
}

mysql_close();
?>

As you notice, the username and password information are supposed to come from variables which are not defined in this file. They are going to be defined in database.inc file, which is required by index.php file. (The connection between the two is established using require_once(..) command.)

Now, clarke connects to the internet and uses WinSCP to connect to the toolserver. He drag-drops this index.php file to the public_html folder, which takes only a few seconds. Now, he needs to know his database username and password. They are both stored in ~/.my.cnf. Here is a code which can parse .my.cnf and get password:

<?php
$toolserver_mycnf = parse_ini_file("/home/".get_current_user()."/.my.cnf");
$toolserver_username = $toolserver_mycnf['user'];
$toolserver_password = $toolserver_mycnf['password'];
unset($toolserver_mycnf);
?>

Then, he uploads this file as database.inc to his home directory (and not to the public_html directory).

Now, in order to test his code, he uses his browser to visit http://toolserver.org/~clarke/index.php. What he will get on that page is the highest value of rev_id column of revision table of enwiki_p database.

Which database, which table?

Definitely, you have to have a good understanding of MediaWiki's database tables structure, to be able to code your projects. Visit Toolserver/For users/Database for more information about the database tables.

Besides that, you need to know which database server to use to have access to the tables of each Wikimdia wiki. At the time of this writing, English Wikipedia's tables are located enwiki_p database hosted on sql-s1 while, for example, French Wikipedia's tabls are located on frwiki_p database hosted on sql-s3. The place each database is hosted on is not supposed to change, but it may change at some point. There is one server which is supposed to remain constant; it is named sql. It does not replicate the information on Wikimedia wikis. Instead, it is a place for toolserver users to store their own data, and, to access some data which is available to all of them. One of the useful pieces of data hosted in this database, is a table listing the servers hosting each Wikimedia wiki replication database. You can query this database like this:

select server from toolserver.wiki where dbname='enwiki_p'

The returned value (at the time of this writing, 'sql-s1') is the name of the database server which hosts the replicated copy of the desired wiki (in the above example, the English Wikipedia).

You can also use <dbname>.db.toolserver.org, which will automatically resolve to the appropriate database server. For example, for English Wikipedia you can use enwiki-p.db.toolserver.org and for French Wikibooks you can use frwikibooks-p.db.toolserver.org. See this message on the toolserver-l mailing list.

Testing projects locally

Wikimedia toolserver is not a place to test your codes. You should test your codes and debug them before you publish them to the toolserver. For this reason, you must be able to run your codes locally.

Installation

You must install MediaWiki first. Go to MediaWiki's home page and choose the appropriate file to download. Read the documentation there, about how to set MediaWiki up and run it on your machine. (You may need to download and install a database server like MySQL, a web server like Apache, as well as PHP itself; this is addressed on MediaWiki web site clearly).

After setting up MediaWiki, you can add a subfolder to your MediaWiki installation (for example named .toolserver) where you can keep a copy of every thing you want to publish to the toolserver later. You can also create a subfolder for the above folder, named public_html, to keep the folder structure as similar to the toolserver as possible.

Importing some data

A clean MediaWiki installation does not provide you with enough data so you can test every aspect of your projects on it. You need to import some data to your local wiki. The easiest way to do this is to download one of the database dumps available here, and import them to your local wiki, as described on this page. A quite good option is to download and import Test wiki.

Importing a database may take several minutes (or even hours) and may use a huge share of your disk space. You also may encounter some issues when importing the data. Addressing these issues and their solutions is beyond the scope of this tutorial. You should have a good understanding of how to work with MySQL databases (or any other database system you have used for your local wiki). You may ask for help on IRC on #mediawiki channel.

There are two common pitfalls which you should avoid:

The database username and password of your local wiki is probably different from that of the toolserver. Please pay attention not to overwrite your files on the toolserver with your local files unless you have made sure they will use the correct username and password to connect to the toolserver databases.
When you install MediaWiki, it allows to use a prefix for the table names of your local wiki. It is a good idea not to use a prefix (leave the box blank during installation). This is because the toolserver databases do not use a prefix for table names, and maintaining a code to work both on your local wiki which uses prefixes and on toolserver where you shouldn't use prefixes, is much harder than installing MediaWiki without prefixes for table names.

Where to find help

You may ask your questions on #wikimedia-toolserver channel on IRC, send email to the toolserver-l mailing list, or to contact Wikimedia toolserver administrators.