Module of the Week: martasd/mediawiki – Deploy Multiple MediaWiki Instances

Purpose Deploy, configure, and manage multiple instances of MediaWiki.
Module martasd/mediawiki
Puppet Version 2.6+
Platforms CentOS 6, Debian 6, and Ubuntu 12.04
A wiki is a very popular way to share information within an organization as well as with the general public. Organizations and individual users who share information using a wiki often need to separate unrelated topics into distinct domains. Although most wiki software such as MediaWiki does not allow for this separation into isolated spaces by design, it is possible to achieve it via multitenancy. In the context of MediaWiki deployment, multitenancy means configuring multiple distinct wiki instances to use the same wiki installation. The objective of this module is to automate the process of Mediawiki installation and allow system administrators to get multiple instances of MediaWiki up and running very easily and quickly.

Installing the Module

Complexity Very Easy
Installation Time 1 minute
The latest version of the module is available on the Puppet Forge, so installation is very straightforward. On the command line, execute:
puppet module install martasd-mediawiki
to install the module with all its dependencies. The module uses Apache web server, which is administered with puppetlabs/apache module, and MySQL as its database backend configured via puppetlabs/mysql module. To ensure better performance, this module also installs and configures Memcached using saz/memcached. All of these dependency modules are also available on the Puppet Forge, so, thanks to the dependency resolution algorithm of the Puppet Module tool, the entire installation is just a one-liner.

Resource Overview

As I mentioned in the introduction, the primary goal of the module is to enable a quick deployment of a new wiki instance. The module’s architecture achieves this by decoupling MediaWiki software installation from the creation of a new wiki instance. In the module, the class mediawiki is responsible for installing the latest version of Mediawiki, while the resource type mediawiki::instance provides the interface for creating a new instance. Thus, in site.pp for the node where you wish to deploy MediaWiki, you first need to declare the class mediawiki in order to ensure that mediawiki is installed:
class { 'mediawiki':
 server_name => 'www.myawesomesite.com',
 admin_email => 'admin@myawesomesite.com',
 db_root_password => 'really_really_long_password',
 doc_root => '/var/www',
 max_memory => '1024'
 }
The above declaration fetches the official tarball with latest version of MediaWiki and installs it into a directory of choice. In addition to that, it also informs Apache of the server name to use and the email address to display when rendering an error page, sets the password for the mysql root user, specifies the webserver document root, and imposes a maximum memory limit for Memcached. Once you ensure that MediaWiki is installed, you can then create new instances like this:
mediawiki::instance { 'my_wiki1':
  db_password => 'really_long_password',
  db_name => 'wiki1',
  db_user => 'wiki1_user',
  port => '80',
  ensure => 'present'
  } 

mediawiki::instance { 'my_wiki2':
  db_password => 'another_really_long_password',
  db_name => 'wiki2',
  db_user => 'wiki2_user',
  port => '80',
  ensure => 'present'
  } 

mediawiki::instance { 'my_wiki3':
  db_password => 'yet_another_really_long_password',
  db_name => 'wiki3',
  db_user => 'wiki3_user',
  port => '80',
  ensure => 'present'
  }
This codeblock creates three separate instances of MediaWiki, each with its own configuration. All wiki instances, however, share the same MediaWiki source files, which means that the overhead of creating a new instance is very low. Each wiki instance puts configuration files in its own directory and stores wiki content in its own database to achieve isolation. Since a wiki instance is implemented as a defined resource type, Puppet imposes no limit on the number of instances you can create. However, there are naturally practical limitations you need to consider, such as the finite amount of memory available. Finally, you need to ensure that all directories on the directory path of Apache’s Document Root exist and have been granted appropriate permissions, so that Apache can serve Mediawiki files. Let’s consider the case when Document Root is configured as /var/www/org1. In this situation, you need to make sure that /var/www/org1 exists and both /var/www and /var/www/org1 are executable by the apache user. To achieve this goal with Puppet on a Debian-based system, add the following to site.pp:
file { '/var/www':
  ensure => 'directory',
  owner => 'root',
  group => 'root',
  mode => '0755', } 

file { '/var/www/org1':
  ensure => 'directory',
  owner => 'www-data,
  group => 'www-data,
  mode => '0755', }
On a RHEL/CentOS system, the owner and group of /var/www/org1 needs to be set to apache instead. To access the first of the newly created MediaWiki instances, enter http://www.myawesomesite.com/my_wiki1 in your browser and unleash your creativity!

Testing the Module

To test the functionality of the module, I chose to use the RSpec testing framework which has emerged as the golden standard for testing Puppet modules. In writing module tests, I followed workflow outlined in The Next Generation of Puppet Module Testing by Branan Purvine-Riley, which provides a very good overview of current best practices in Puppet module testing. To run RSpec tests, execute rake spec. Currently, our integration testing environment reports that all tests are passing for Ruby versions 1.8.7 and 1.9.3 in combination with Puppet versions 2.6.9, 2.7.9, 2.7.13, and 2.7.13 (with the exception of the earliest version of Puppet 2.6.9 and latest version of Ruby 1.9.3, which are fundamentally incompatible). To check on the current status of RSpec tests for the version combinations described above, visit MediaWiki Integration Testing. I am planning to add support for the upcoming Puppet 3.0 once it is released. If you notice a failing test, encounter a bug while using the module, or think of an important test case which I have not covered with RSpec, don’t hesitate to fix the issue and submit a pull request on GitHub, or file a bug report at Puppet MediaWiki Issues. Any contributions are greatly appreciated.

Configuring the Module

Besides options included in the example declaration above, there are a number of additional parameters you might be interested in tweaking. As I mentioned earlier, the module installs MediaWiki from a tarball. I chose to use a tarball over a package because packages of most popular distros offer outdated versions of the software which do not allow to fully automate the creation of a wiki instance. The module, however, does offer an option for the user to choose the particular version that is installed by specifying the URL of the tarball:
class { 'mediawiki':
  server_name => 'www.example.com',
  admin_email => 'admin@puppetlabs.com',
  db_root_password => 'really_really_long_password',
  tarball_url => 'http://download.wikimedia.org/mediawiki/1.17/mediawiki-1.17.0.tar.gz',
  doc_root => '/var/www',
  max_memory => '1024',
  }
The declaration above installs an earlier version of MediaWiki, 1.17.0, instead of the latest default version 1.19.1. Furthermore, the mediawiki::instance resource type allows you to configure the IP address and port of the web server which serves the wiki content as well as to specify server aliases. These options provide a greater flexibility in configuring individual wiki instances. An example declaration which takes advantage of these options might look like this:
mediawiki::instance { 'special_wiki':
  db_password => 'very_very_long_password,
  db_name => 'wiki3',
  db_user => 'wiki3_user',
  ip => '192.168.100.42',
  port => '80',
  server_aliases => 'puppetmaster',
  ensure => 'present ' }
For the complete list of configuration options and their description, see the module documentation.

Conclusion

If you are looking for a solution to make the process of creating multiple MediaWiki instances more efficient in your environment, this module is just for you. By automating the entire process of MediaWiki installation and instance creation, the module can potentially save you a substantial amount of time. Currently, the module does not automate the installation and configuration of MediaWiki extensions which need be added manually after the installation with Puppet is finished. But do not despair! Adding support for MediaWiki extensions is at the top of my TODO list for the module and you can expect this functionality in the near future. If there are more features you are missing in the module, let me know at martin@gnu.org or contribute them yourself! Learn More:
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.