Help:Tool Labs

From Wikitech

Tool Labs is a hosting environment for community developers working on tools and bots that help users maintain and use wikis. Tool Labs provides access to replicas of Wikimedia databases, allowing developers to easily re-use this information, for analytics, bot work, or by creating tools that help editors and other volunteers in their work. The infrastructure is supported by a dedicated group of Wikimedia Foundation staff and volunteers.

Quick start

  1. On wikitech, visit Create an account and create your Labs wiki account.
    • make careful note of the wiki username and "Instance shell account name" you choose
  2. On wikitech, Fill out an access request for the Tools project.
  3. In a command-line terminal, generate an SSH-2 RSA key. See /Access § Generating and uploading an SSH key if you don't know how.
  4. In a command-line terminal, enter: $ cat ~/.ssh/ (or similar) to display your public SSH key that you created above, then copy it.
  5. On wikitech, log in with your labs wiki account, visit Preferences > OpenStack tab and paste in your public SSH key.
  6. Wait for your requests to be completed (you should receive messages on your wikitech talk page).

Once this is all done you should be able to

  • Use SSH to login to Tool Labs. In a command-line terminal, enter: ssh -i ~/.ssh/id_rsa (username is the "Instance shell account name" you specified when you created an account)
  • Use SSH-based utilities such as scp and sftp to transfer files between Tool Labs and your computer.
  • Access MySQL from SSH (e.g. sql enwiki is a shortcut command to connect to the copy of English Wikipedia)
  • Create tools (see § Creating a new Tool account).


  • Your wikitech wiki username and your shell login username may be different. Visit Preferences > User profile and check "Instance shell account name".
  • The passwords you chose for your wikitech login and SSH key may be different.
  • You will notice that you have no public_html in your home folder, unlike the old Toolserver. This is because you need to create and use the Tool account to serve services.
  • When you login with SSH you are in your personal folder. To quickly go to your tool account enter: become tool_name
  • If you login with WinSCP you transfer files as yourself (not as your tool). The group is the same so you can just do:
become <tool_name>
chmod -R g+rw ./
  • You will also notice that web service for your tool is not started by default. To start it enter: webservice start

What is Tool Labs


Tool Labs was developed in response to the need to support external tools and their developers and maintainers. The system is designed to make it easy for maintainers to share responsibility for their tools and bots, which helps ensure that no useful tool gets ‘orphaned’ when one person needs a break. The system is designed to be reliable, scalable and simple to use, so that developers can hit the ground and start coding.


In addition to a well-supported hosting environment, Tool Labs provides:

  • support for Web services, continuous bots, and scheduled tasks
  • access to replicated production databases
  • easily shared management of tool accounts, where tools and bots are stored
  • a grid engine for dispatching jobs
  • support for mosh, SSH, SFTP without complicated proxy setup
  • version control via Gerrit and Git
  • support for Redis

Shared storage

You will have access to some of the shared storage, see Help:Shared storage (for instance the /shared/mediawiki/ checkout).

Architecture and terminology

Tool Labs has four components: the bastion hosts , the grid, the web cluster, and the databases.

Bastion hosts

You log in to Tool Labs through a bastion host. As of May 2015, Tool Labs has two bastion hosts:
user login to access tools interactively, also named
functionally identical, please use this for heavy processing such as compiles
The grid

The Tool Labs grid, implemented with Open Grid Engine (the open-source fork of Sun Grid Engine) permits users to submit jobs from either a log-in account on the bastion host or from a web service. Submitted jobs are added to a work queue, and the system finds a host to execute them. Jobs can be scheduled synchronously or asynchronously, continuously, or simply executed once. If a continuous job fails, the grid will automatically restart the job so that it keeps going. For more information about the grid, please see § Submitting, managing and scheduling jobs on the grid.

The web cluster

The Tool Labs web cluster is fronted by a web proxy, which supports SSL and is open to the Internet. The proxy distributes web requests among the web servers in this cluster; any server in this web cluster can serve any of the hosted web tools because Tool Labs uses a shared storage system. For more information, please see § Web server.

Each tool has its own lighttpd Web server, with full configuration options. FCGI scripts are supported with configuration options, and WSGI is supported using flup.server.fcgi. See § Web server for more information.

The databases

Tool Labs supports two sets of databases: the production replicas and user-created databases, which are used by individual tools. The production replicas follow the same setup as production, and the information that can be accessed from them is the same as that which normal registered users (i.e.: not +sysop or other types of advanced permissions) can access on-wiki or via the API. Note that some data has been removed from the replicas for privacy reasons. User-created databases can be created by either a user or a tool on the replica servers or on a local ‘tools’ project database.

No "instances"

Developers working in Tool Labs do not have to create or set up virtual machines (i.e., Labs "instances"), because the Tool Labs project admins create and manage them. The term may appear in documentation on Wikitech, otherwise, don’t worry about it.

Rules of use

Tool Labs policies

All tools and bots developed and maintained on Tool Labs must adhere to the terms of use that will be available here when they are finalized:

Specifically, tools must be

Private information must be handled carefully, if at all. Note that private user information has been redacted from the replicated databases provided by the system.

As the Tool Labs environment is shared, we ask that you strive not to break things for others, and to be considerate when using system resources.

Individual wiki policies (these differ!)

When developing on Tool Labs, please adhere to the bot policies of the wikis your bot interacts with. Each wiki has its own guidelines and procedures for obtaining approval. The English Wikipedia, for example, requires that a bot be approved by the Bot Approvals Group before it is deployed, and that the bot account be marked with a 'bot' flag. See Wikipedia Bot policy for more information on the English Wikipedia.

For general information and guidelines, please see Bot policy.


We’d love to hear from you! Our main point of contact is our phabricator project. If you need support, please file a Task there.

Other contact options are:

#wikimedia-labs connect on Freenode, a great place to ask questions, get help, and meet other Tool Labs developers. See Help:IRC for more information.
Mailing list A list for announcements and discussion related to the Wikimedia Labs project. (archives)

or the announce-only version: labs-announce (archives)

Tool Labs is a joint WMF-Volunteer run project, and we welcome contributions to the infrastructure. The current maintainers are:

Getting access to Tool Labs

This is a brief summary of the /Access documentation page.

To access Tool Labs you need:

  • to create a Labs account, which will allow you shell access; and
  • to request access to the 'tools' project

Sign up for a Labs account here: Request account (you will be asked to enter the new account's information)

The "Instance shell account name" you specify in the Create Account form will be your Unix username on all Labs projects. If you forget your username, you can always find it under Preferences > Instance shell account name.

In order to access Labs servers using SSH, you must provide a public SSH key. Once you have created a Labs account, you can specify a public key on the 'OpenStack' tab of your Wikitech preferences.

Once you have created a Labs account, you must request access to the ‘tools’ project by submitting a Tools Access Request. Requests for access are generally dealt with within the day (often faster), though response-time may be longer depending on admin availability. If you need immediate assistance, please contact us on IRC.

Using Tool Labs and managing your files

Tool Labs can be accessed in a variety of ways – from its public IP to a GUI client. Please see Help:Access for general information about accessing Labs.

The tools list

The Tool labs tools list page is publicly available and contains a list of all currently-hosted Tool accounts along with their maintainers. Tool accounts that have an associated web page appear as links. Users with access to the 'tools' project can create new tool accounts here, and add or remove maintainers to and from existing tool accounts.


Once set up, you ssh to Tool Labs via its bastion host, provided that a public SSH key has been uploaded to the Labs account.


Note that if you plan to do heavy processing (compiling, etc), you should SSH to

Using multiple ssh agents

If you use multiple ssh-agents (to connect to your personal or company system, for example), see SSH access for more information about setting up a primary and a Labs agent.

Updating files

After you can ssh successfully, you can transfer files via sftp and scp. Note that the transferred files will be owned by you. You will likely wish to transfer ownership to your tool account. To do this:

1. become your tool account:

yourshellaccountname@tools-login:~$ become toolaccount

2. As your tool account, take ownership of the files:

tools.toolaccount@tools-login:~$ take FILE

The take command will change the ownership of the file(s) and directories recursively to the calling user (in this case, the tool account).

Handling permissions

if you're getting permission errors, note that you can also transfer files the other way around: copy the files as your tool account to /data/projects/<projectname>.

Another, probably easier, way is to set the permission to group-writable for the tools directory. For example, if your shell account's name is alice and your tool name is alicetools you could do something like this after logged in as a shell user

become alicetools
chmod -R g+w /data/project/alicetools
cp -rv /home/alice/* /data/project/alicetools/

Using git

The best option is to create a Git repository to which project participants commit files. To access the files, become the tool account, check that repository out in your tool's directory, and thereafter run a regular git pull whenever you want to deploy new files.

Putty and WinSCP

Note that instructions for accessing Tool Labs with Putty and WinSCP differ from the instructions for using them with other Labs projects. Please see Help:Access to ToolLabs instances with PuTTY and WinSCP for information specific to Tool Labs.

Other graphical file managers (e.g., Gnome/KDE)

For information about using a graphical file manager (e.g., Gnome/KDE), please see Accessing instances with a graphical file manager.

Installing MediaWiki core

Warning Warning: MediaWiki installations attract spammers faster than anything else, and the load caused makes Tools administrators grumpy. Do lock down your installation immediately after setup so that uninvited users cannot publish information. You should also re-read the Terms of use regarding the rules on wikis.

You want to install MediaWiki core and make your installation visible on the web.

One-time steps per tool

First, you have to do some preparatory steps which you need only once per tool.

become <YOURTOOL>

If you have not installed composer yet:

mkdir ~/bin
curl -sS | php -- --install-dir=~/bin --filename=composer

If your local bin directory it not in your $PATH (use echo $PATH to find out), then create or alter the file ~/.profile and add the lines:

# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/bin" ] ; then

Finish your session as <YOURTOOL> and start a new one, or:

. ~/.profile

Now you are done with the one-time preparations.

For each instance of core

The following steps are needed for each new installation of MediaWiki. We assume that you want to access MediaWiki via the web in a directory named MW — you are free to use another name. If not already done:

become <YOURTOOL>


cd ~/public_html

If you plan to submit changes:

git clone ssh://<YOURUSERNAME> MW

or else, if you only want to use MediaWiki without submitting changes:

git clone MW

will do and spares resources. Next, recent versions of MediaWiki have external dependencies, so you need to install those:

cd MW
composer install
git review -s

Now you should be able to access the initial pre-install screen of MediaWiki from your web browser as:<YOURTOOL>/MW/

and proceed as usual. See how to create new databases for your MediaWiki installations.

Joining and creating a Tool account

What is a Tool account?

A Tool account is the "user" associated with a Tool on Tool labs. Although each tool account has a user ID, they are not personal accounts (like a Labs account), rather services that consist of a user and group ID (i.e., a unix uid-gid pair) that are intended to run the actual tool or bot. Anyone who has access to Tool Labs can create a Tool account.

  • Unix user: tools.toolname
  • Unix group: tools.toolname

Members of the Tool account's Unix group include:

  • the tool account creator
  • the tool account itself
  • (optionally, but encouraged!) additional tool maintainers

Maintainers may have more than one tool account, and tool accounts may have more than one maintainer. Every member of the group has the authorization to sudo to the tool account. By default, only members of the group have access to tool account's code and data.

A simple way for maintainers to switch to the tool account is with become:

maintainer@tools-login:~$ become toolname

In addition to the user/group pair, each tool account includes:

  • A home directory on shared storage: /data/project/toolname
  • A ~/public_html/ directory, which is visible at
  • Database access credentials: ~/, which provide access to the production database replicas as well as to project-local databases.
  • Access to the continuous and task queues of the compute grid

Joining an existing Tool account

All tool accounts hosted in Tool Labs are listed on the Tools home page. If you would like to be added to an existing account, you must contact the maintainer(s) directly.

If you would like to add (or remove) maintainers to a tool account that you manage, you may do so with the 'add' link found beneath the tool name on the Tools home page.

Creating a new Tool account

Members of the ‘tools’ project can create tool accounts from the Tools home page:

  1. Navigate to the Tools home page.
  2. Select the "create new tool" link (found beside "Hosted tools" near the top of the page.
  3. Enter a "Service group name". The service group name will be used as the name of your tool account.

Do not prefix your service group name with tools.. The management interface will do so automatically where appropriate, and there is a known issue that will cause the account to be created improperly if you do.

Note: If you have only recently been added to the 'tools' project, you may get an error about not having appropriate credentials. Simply log out and back in to Wikitech to fix this

The tool account will be created and you will be granted access to it within a minute or two. If you were already logged in to your Labs account through SSH, you will have to log off then back in before you can access the tool account.

Deleting a Tool account

You can't delete a tool account yourself, though you can delete the content of your directories. If you really want a tool account to be deleted, please contact an admin.

Customizing a Tool account

Once you have created a tool account, there are a few things that you can customize to make the tool more easily understood and used by other users. These include:

  • adding a tool account description (the description will appear on the Tools home page beside the tool name)
  • creating a home page for your tool (if you create a home page for the tool, it will be linked from the Tools home page automatically)

Tool Labs will soon support mail to both Labs users and tool accounts (mail to a tool account will go to all maintainers by default). You can customize mail settings as well.

Creating a tool web page

To create a web page for your tool account, simply place an index.html file in the tool account's ~/public_html/ directory. The page can be a simple description of the tool or bot with basic information on how to set it up or shut it down, or it contain an interface for the web service. To see examples of existing tool web pages, click any of the linked tool names on the Tools home page.

Note that some files, such as PHP files, will give a 500 error unless the owner of the file is tool account.

You will also need to start a webservice for your tool.

1. Log into your Labs account and become your tool account:

maintainer@tools-login:~$ become toolname

2. Start the web service:

tools.toolname@tools-login:~$ webservice start

Make the tool translatable

If your tool is used from the web, and assuming you think it's worth something at all, you want to make it translatable. You can and should use the Intuition framework (PHP only), which allows you to use and delivers you the localisation.

Don't waste your time, learn from our experience with MediaWiki: read the message documentation tips and other internationalization hints.

Creating a tool description

To create a tool description:

1. Log into your Labs account and become your tool account:

maintainer@tools-login:~$ become toolname

2. Create a .description file in the tool account’s home directory. Note that this file must be HTML:

tools.toolname@tools-login:~$ vim .description

3. Add a brief description (no more than 25 words or so) and save the file.

4. Navigate to the Tools home page. Your tool account description should now appear beside your tool account name.

Configuring bots and tools

Tools and bot code should be stored in your tools account, where it can be managed by multiple users and accessed by all execution hosts. Specific information about configuring web services and bots, along with information about licensing, package installation, and shared code storage, is available at the § Developing on Tool Labs section.

Note that bots and tools should be run via the grid, which finds a suitable host with sufficient resources to run each. Simple, one-off jobs can be submitted to the grid easily with the jsub command. Continuous jobs, such as bots, can be submitted with jstart.

Setting up code review and version control

Although it's possible to just stick your code in the directory and mess with it manually every time you want to change something, your future self and your future collaborators will thank you if you instead use source control, a.k.a. version control and a code review tool. Wikimedia Labs makes it pretty easy to use Git for source control and Gerrit for code review, but you also have other options.

Setting up a local Git repository

It is fairly simple to set up a local Git repository to keep versioned backups of your code. However, if your tool directory is deleted for some reason, your local repository will be deleted as well. You may wish to request a Gerrit/Git repository to safely store your backups and/or to share your code more easily. Other backup/versioning solutions are also available. See User:Magnus Manske/Migrating from toolserver § GIT for some ideas.

To create a local Git repository:

1. Create an empty Git repository

maintainer@tools-login:~$ git init

2. Add the files you would like to backup. For example:

maintainer@tools-login:~$ git add public_html

3. Commit the added files

git commit -m 'Initial check-in'

For more information about using Git, please see the git documentation.

Enabling simple public HTTP access to local Git repository

If you've set up a local Git repository like the above in your tool directory, you can easily set up public read access to the repository through HTTP. This will allow you to, for instance, clone the Git repository to your own home computer without using an intermediary service such as GitHub.

First create the www/static/ subdirectory in your tool's home directory, if it does not already exist:

mkdir ~/www
mkdir ~/www/static/

Now go to the www/static/ directory, and make a symbolic link to your bare Git repository (the hidden .git subdirectory in the root of your repository):

cd ~/www/static/
ln -s ~/.git yourtool.git

Now change directory into the symbolic link you just created, and run the git update-server-info command to generate some auxiliary info files needed for the HTTP connectivity:

cd yourtool.git
git update-server-info

Enable a few Git hooks for updating said auxiliary info files every time someone commits, rewrites or pushes to the repository:

ln -s hooks/post-update.sample hooks/post-commit
ln -s hooks/post-update.sample hooks/post-rewrite
ln -s hooks/post-update.sample hooks/post-update
chmod a+x hooks/post-update.sample

You're done. You should now be able to clone the repository from any remote machine by running the command:

git clone

Requesting a Gerrit/Git repository for your tool

Tool Labs users may request a Gerrit/Git repository for their tools. Access to Git is managed via Wikimedia Labs and integrated with Gerrit, a code review system.

In order to use the Wikimedia Labs code review and version control, you must upload your ssh key to Gerrit and then request a repository for your tool.

  1. Log in to with your Labs account.
  2. Add your SSH public key (select “Settings” from the drop-down menu beside your user name in the upper right corner of the screen, and then “SSH Public Keys” from the Settings menu).
  3. Request a Gerrit project for your tool: Gerrit/New repositories

For more information, please see:

For more information about using Git and Gerrit in general, please see Git/Gerrit.

Using Github or other external service

Before you start you might want to setup your Git user account.

# Login to your tool account
become mytool
# Your name
git config "Your Name"
# Your e-mail (use the one you set up in Github)
git config ""

Then you can clone remote repo (as you always do):

git clone

You can do updates any way you want, but you might want to use this simple update script to securely update code:


read -r -p "Stop the service and pull fresh code? (Y/n)" response
if ! [[ $response =~ ^([nN][oO]|[nN])$ ]]
	webservice stop
	cd ./public_html
	echo -e "\nUpdating the code..."
	git pull
	read -r -p "OK to start the service? (Y/n)" response
	if ! [[ $response =~ ^([nN][oO]|[nN])$ ]]
		webservice start

Save above in your tool account home folder as e.g. "". Don't forget to add executive rights to you and your tool group (i.e. `chmod 770`).

Database access

This is a brief summary of the /Database documentation page.

Tool and Labs accounts are granted access to replicas of the production databases. Private user data has been redacted from these replicas (some rows are elided and/or some columns are made NULL depending on the table), but otherwise the schema is, for all practical purposes, identical to the production databases and the databases are sharded into clusters in much the same way.

Database credentials (credential user/password) are stored in the '' file found in the tool account’s home directory. To use these credentials with command-line tools by default , copy '' to '.my.cnf'.

If you do not have a '' in your home directory, please create a ticket in Phabricator.

To connect to the English Wikipedia replica, specify the alias of the hosting cluster (enwiki.labsdb) and the alias of the database replica (enwiki_p) :

mysql --defaults-file="${HOME}"/ -h enwiki.labsdb enwiki_p

To connect to the Wikidata cluster:

mysql --defaults-file=~/ -h wikidatawiki.labsdb

To connect to Commons cluster:

mysql --defaults-file=~/ -h commonswiki.labsdb

There is also a shortcut for connecting to the replicas: sql <dbname>[_p] The _p is optional, but implicit (i.e. the sql tool will add it if absent).

To connect to the English Wikipedia database replica using the shortcut, simply type:

sql enwiki

Submitting, managing and scheduling jobs on the grid

This is a brief summary of the /Grid documentation page.

Every non-trivial task performed in Tool Labs should be dispatched by the grid engine, which ensures that the job is run in a suitable place with sufficient resources. The basic principle of running jobs is fairly straightforward:

  • You submit a job to a work queue from a submission server (e.g., -login) or web server
  • The grid engine master finds a suitable execution host to run the job on, and starts it there once resources are available
  • As it runs, your job will send output and errors to files until the job completes or is aborted.

Jobs can be scheduled synchronously or asynchronously, continuously, or simply executed once. If a continuous job fails, the grid will automatically restart the job so that it keeps going.

To schedule jobs to be run at specific days or time of days, you can use cron to submit the jobs to the grid.

Scheduling a command more often than every five minutes (for example * * * * * command) is highly discouraged, even if the command is "only" jsub. In these cases, you very probably want to use 'jstart' instead. The grid engine ensures that jobs submitted with 'jstart' are automatically restarted if they exit.


Mail to users

Mail sent to (where user is a shell account) will be forwarded to the email address that user has set in their Wikitech preferences, if it has been verified (the same as the 'Email this user' function on wikitech).

Any existing .forward in the user's home will be ignored.

Mail to tools

Mail can also be sent "to a tool" with:

Where "anything" is an arbitrary alphanumeric string. Mail will be forwarded to the first of:

  • The email(s) listed in the tool's ~/.forward.anything, if present;
  • The email(s) listed in the tool's ~/.forward, if present; or
  • The wikitech email of the tool's individual maintainers.

Additionally, is an alias pointing to mostly useful for automated email generating from within Labs.

~/.forward and ~/.forward.anything need to be readable by the user Debian-exim; to achieve that, you probably need to chmod o+r ~/.forward*.

Processing email programatically

In addition to mail forwarding, tools can have incoming mail sent to an arbitrary program by setting one of its .forwards (as above) to:

|jmail program

In that case, program will be invoked as a job on the grid and will have the email presented to it as its standard input. If program fails to run, or exits with a non-zero status, then the email will bounce with the standard error included it the bounce message.

Please be aware that mail processing on the grid is limited in memory and in runtime (30s CPU time, 60s wall clock) so you should not do heavy processing in your script. If you need more than this, then have the initial script simply queue the email for later processing from another component.

Mail from tools

When sending mail from a job, the usual command line method of piping the message body to /usr/bin/mail may not work correctly because /usr/bin/mail attempts to deliver the message to the local MSA in a background process which will be killed if it is still running when the job exits.

If piping to a subprocess to send mail is needed, the message including headers may be piped to /usr/sbin/exim -odf -i.

# This does not work when submitted as a job
echo "Test message" | /usr/bin/mail -s "Test message subject"

# This does
echo -e "Subject: Test message subject\n\nTest message" | /usr/sbin/exim -odf -i
  • Note: /usr/bin/echo supports -e in case your shell's internal echo command doesn't.

Web server

This is a brief summary of the /Web documentation page.

Every tool can have a dedicated web server started on a dedicated queue of the grid; that web server is lighttpd by default (documentation).

It is also possible to run your own webserver (e.g. to run a Scala-based tool). You can start your web server (from the tool account) with the command:

webservice start

Likewise, you can use the webservice command to stop and restart your server, or to request its status.

Developing on Tool Labs

This is a brief summary of the /Developing documentation page.

All code in the ‘tools’ project must be open source. Please add a license at the beginning! Even if you have not yet deployed or finished your work, it is non-free software unless you explicitly license it.

You may use any free license of your choice, provided that it is OSI approved. The full documentation page provides tips and instructions for developing code in the Tool Labs, including specific language support.


Redis is a key-value store similar to memcache, but with more features. It can be easily used to do publish/subscribe between processes, and also maintain persistent queues. Stored values can be different data structures, such as hash tables, lists, queues, etc. Stored data persists across service restarts. For more information, please see the Wikipedia article on Redis.

A Redis instance that can be used by all tools is available on tools-redis, on the standard port 6379. It has been allocated a maximum of 12G of memory, which should be enough for most usage. You can set limits for how long your data stays in Redis; otherwise it will be evicted when memory limits are exceeded. See the Redis documentation for a list of available commands.

Libraries for interacting with Redis from PHP (phpredis) and Python (redis-py) have been installed on all the web servers and exec nodes. For an example of a bot using Redis, see SuchABot.

For quick & dirty debugging, you can connect directly to the Redis server with nc -C tools-redis 6379 and execute commands (for example "INFO").


Redis has no access control mechanism, so other users can accidentally/intentionally overwrite and access the keys you set. Even if you are not worried about security, it is highly probably that multiple tools will try to use the same key (such as lastupdated, etc). To prevent this, it is highly recommended that you prefix all your keys with an application-specific, lengthy, randomly generated secret key.

You can very simply generate a good enough prefix by running the following command:

openssl rand -base64 32

PLEASE PREFIX YOUR KEYS! We have also disabled the redis commands that let users 'list' keys.

Can I use memcache?

There is no memcached on toollabs. Please use Redis instead.


The 'tools' project, like all labs projects, has access to a directory storing the public Wikimedia datasets (i.e. the dumps generated by Wikimedia). The most recent two dumps can be found in:


This directory is read-only, but you can copy files to your tool's home directory and manipulate them in whatever way you like.

If you need access to older dumps, you must manually download them from the Wikimedia downloads server.

/public/dumps/pagecounts-raw contains some years of the pagecount/projectcount data derived by Erik Zachte from Domas Mituzas' archives.

CatGraph (aka Graphserv/Graphcore)

CatGraph is a custom graph database that provides tool developers fast access to the Wikipedia category structure. For more information, please see the documentation.


If you run into problems, please see the § Contact section. Specifically, please feel free to come into #wikimedia-labs connect and look for Coren (Marc-Andre Pelletier) or petan (Petr Bena). The labs-l mailing list is another good place to ask for help, especially if the people in chat are not responding.

You can also search help pages, or look more widely with the Google custom search.


What gets backed up?

The basic rule is: There is a lot of redundancy, but no user-accessible backups. Tool Labs users should make certain that they use source control to preserve their code, and make regular backups of irreplacable data. With luck, some files may be recoverable by Labs administrators in a manual process. But this requires human intervention and will likely not rescue the file that was created five minutes ago and deleted two minutes ago. If necessary, ask on IRC or file a Phabricator task.


Do I explicitly have to specify the license of my tools?

Yes. If you think "this is just a draft, nothing ready" and you do not put a license into your code it's non-free software contradicting the idea of Tool Labs. So please add a license in the beginning! You can use any OSI-approved license. Read more on the licenses on the Open Source Initiative's website:

What about file permissions? Who can see my code?

You have full control over access permissions of your code and data. By default, permissions are 0644, meaning everyone can read files, but only the creator of the file can edit them.

Do stewards have a specific project on WMF Labs?

There is no plan to have distinct projects for different tool makers; but the tools are separated from each other. There is nothing that prevents you from sharing the maintenance of some tools between different stewards (in fact, it is recommended that you do so to ensure that there is always someone able to keep them up at need).

Can I delete a tool?

No, you can't do this yourself. The reason is that you or other members might accidentally delete precious stuff. You can delete the content of your directories. If you really want a tool / a service group to be deleted, please contact an admin.

If you are planning to try out Tool Labs but don't know yet if you are going to keep our tests as a later project, don't hesitate to create a tool (a service group) and to create a new one later where you put the stuff you want to keep.

Can I rename a tool?

No, sorry, this is not possible. You'd have to create a new one and put your code in there.

Can I have a subdomain for my web service?

Sorry, not yet. This is still in discussion at WMF. Currently, your web services are available under<YOURTOOL>.

How do I access the database replicas?

  • In your home directory you find your credentials for mariadb (in the file You need to specify this file and the server you want to connect to. Some examples:
mysql --defaults-file=~/ -h enwiki.labsdb # <- for English WP
mysql --defaults-file=~/ -h dewiki.labsdb # <- for German language WP
mysql --defaults-file=~/ -h wikidatawiki.labsdb # <- for Wikidata
mysql --defaults-file=~/ -h commonswiki.labsdb # <- for Commons
  • Alternatively you can rename the credentials file from to .my.cnf and just run
mysql -h commonswiki.labsdb # <- for Commons

Why can't I access user preferences in the replicas?

The db replication gives access to everything that is visible for logged-in users without special privileges. Others' user preferences are considered private information in Wikimedia Labs and are thus redacted from the replicas.

Why am I getting errors about must be installed for pthread_cancel to work?

Encountering this while trying to run jobs on the grid engine means you need to give your job more memory; the (obscure) error message is caused by the system being unable to load your executable and all its shared libraries. As a rule, most scripting language require around 300-350M of virtual memory to load completely. See Allocating additional memory for more information.

Is there a GUI tool for database work?

Not in Tool Labs, but you can run one locally on your computer (for example the MySQL Workbench Here is how you connect to the database:

>For the login:
>For the database, it depends on the exact one you want to use, of course - for example: enwiki.labs

Why does public_html not work in my home directory?

Users do not and cannot have a public_html folder to themselves. The only web-accessible directories are under /data/project/<toolname>/public_html/. To have a URL such as<username>/, you must create a tool called <username>, which will create a folder called /data/project/<username>/public_html/. Nobody--except you, the user--will *ever* be given access to your home or its files. Allowing public services to run from a home directory means that their management could not be shared or taken over if they end up abandoned, defeating the purpose.

I get a Permission denied error when running my script. Why's that?

Make sure that you are running your script from your tool account rather than your user account.

How can I detect if I'm running in Labs? And which project (tools or toolsbeta)?

There is a file that contains the project name on every labs instance: /etc/wmflabs-project.

Testing for its presence tells you "you are in the WMF Labs", and checking its contents will tell you which project; that would be "tools" for the Tool Labs, or "toolsbeta" for the experimental tool labs.

If using PHP check out: $_SERVER['INSTANCENAME'] and $_SERVER['INSTANCEPROJECT'] which contain strings of the current location such as 'tools-login' and 'tools'.

My connection seems slow. Any advice?

When connecting to Tool Labs from Europe you might have higher ping times. Try using mosh ( To connect, use mosh -a (-a to force predictive echo) (instead of ssh

My tool requires a package that is not currently installed in Tool Labs. How can I add it?

You might not be the only one missing that package. Please submit a ticket in Phabricator and ask the admins to install it project-wide. If they have reasons not to do so you can always install software locally / just for yourself.

Note that for python packages, we highly recommend that you use a virtualenv local to your tool - and only request a global package if it is painful to install via pip (numpy, scipy, etc). For example to install the python package internetarchive run

virtualenv ~/env
source $HOME/env/bin/activate
echo "source $HOME/env/bin/activate" >> .bashrc
pip install internetarchive

See also Help:Tool Labs/Python application stub on how to get a sample flask python application installed onto the tools-project as quickly as possible.

My tool needs a more specialized infrastructure than Tool Labs provides. What should I do?

Tool Labs is a simplified environment intended to be a direct toolserver replacement for most small tools. When you need something more complicated or when you need to manage specialized infrastructure, what Tool Labs can't do you can probably do with your own Labs project! (Instead of inside one of the projects "tools" or "toolsbeta".)

I keep reading about puppet. What is it?

As a tool maintainer you don't have to worry about puppet: if you're missing some dependency for your tool, see § My tool requires a package that is not currently installed in Tool Labs. How can I add it?.

The nutshell: puppet is a system by which you describe the configuration of a machine. When used, it will apply the necessary changes to make the machine you apply it to match that configuration.

In practice, the sysadmin would make any change of configuration intended for the machine in puppet (including what to install, files to edit, etc) so that it can be reapplied to a blank machine to configure it "just like it was", or to make a clone, and so on. Puppet is used by the Tools Labs sysadmins so that every server (current and future) is configured without manual intervention.

On Tool Labs the code you write for your tools lives on a shared filesystem rather than on the individual machines, so it has nothing to do with puppet. If however you use other Wikimedia Labs instances, see Help:Instances § Puppet information.

What is the labsconsole?

It's the old name of what is now Wikitech. (

Are there any plans for adding monitoring or profiling tools?

Yes, in the very long term and not guaranteed. Want to help? Find out more here: User:Yuvipanda/Icinga for tools

SSH warns me about differing keys, is Labs compromised?

If you get an error such as

Warning: the ECDSA host key for '' differs from the key for the IP address ''

it most likely just means that the key has been updated (which should normally have been announced on the Labs-l mailing list). Try refreshing it with

ssh-keygen -R <ip>