Setup a render server on Ubuntu 12.04 LTS

The Collection extension is a way to download single pages or generate complete books from articles on your wiki. It is also used on MediaWiki & the Wikipedia sites. The Pdf Export extension can also be used to output pages to pdf. These extensions can use a public render server to render the output like the one at PediaPress used by MediaWiki and the Wikipedia websites. If you can't or don't want to use a public render server it is relatively easy to setup your own render server. There is documentation on the subject but depending on what you want your render server to do you need to combine a lot of sources on the web and several Talk pages on MediaWikia. Because of this setting up your own render server can be a little frustrating. This document is an attempt to make the process more clear and hopefully a little less frustrating.

It is possible to setup a render server on many different Linux distro's or even on a MS Windows box but even with just some basic Linux know-how it is "easier" to use a Linux distro. When you are "forced" into a MS Windows environment and you can't setup a Linux box you could use VirtualBox, or any other virtualization software on the Windows host and virtualize your Linux distro. You will still be able to run your own render server, this works just fine.

Because there is already some documentation how to setup a render server on Ubuntu 10.04 LTS the 64 bit desktop version of Ubuntu 12.04 LTS was used to write this documentation. The 32 bit version will probably also work but was not used.

What you get is your own render server that outputs pdf files from a MediaWiki wiki.

Install Ubuntu
Install a clean version of Ubuntu 12.04 LTS (64 bit desktop). After installation process is finished and Ubuntu has restarted your "render server" needs to be connected to the internet to be able to install the rest of the software. When you have a direct connection all is fine but if you have to go trough a proxy server then one way of setting this up is to use the  file located in. Type:
 * 1) Add the following line with your own user and proxy setup:
 * 2) Then save the file.
 * 1) Then save the file.
 * 1) Then save the file.

Update Ubuntu
After Ubuntu has restarted you can wait for the Update Manager to open but you can also open a terminal screen and type: After the package list is updated type: When finished you probably need to restart Ubuntu if not it will not hurt to restart anyway.

Install Python and other dependencies
To be able to run your render server you need Python and some other dependencies. Python is included in the default installation of the desktop version of Ubuntu 12.04 but to make sure that Python and the other dependencies are installed open a terminal screen and paste the below code in the screen. Not sure if you need all of them but it works: When finished you probably don't need to restart Ubuntu but it will not hurt to restart anyway.

Install mwlib & mwlib.rl
mwlib provides a library for parsing MediaWiki articles and converting them to different output formats.

You need to be root to install mwlib so use sudo.


 * mwlib is the core functionality, provides a parser.
 * mwlib.rl generates PDF files from MediaWiki articles. This is what is being used on Wikipedia in order to generate PDF output.

Math formulas support
If you are using the Math or MathJax extensions and you want to render formulas in your pdf output you also need to install support files for MediaWiki. You probably don't need all of it but it works. In a terminal screen run:

Create a cache directory
Before you can start your render server you need to create a cache directory and make it accessible for your Ubuntu user. To do this type the following commands in a terminal screen:
 * Replace  with your Ubuntu user under which the render server will run
 * Replace  with your Ubuntu user under which the render server will run
 * Replace  with your Ubuntu user under which the render server will run
 * Replace  with your Ubuntu user under which the render server will run

Start your server
There are multiple solutions on how to start your server. To understand what is going on, first open 3 terminal screens and start the following python scripts, one in each of the screens: If you are using a print-on-demand service (the  parameter in LocallSettings.php) open another terminal screen to start:


 * nserve is a HTTP server. The Collection extension is talking to that program directly. nserve uses at least one mw-qserve instance in order to distribute and manage jobs . Please note that nserve does not allow you to have your mediawiki base_url (equivalent to $wgServer in LocalSettings.php) set to localhost or an IP beginning with 127.0. or 192.168. 
 * mw-qserve is a job queue server used to distribute and manage jobs. You should start one mw-qserve instance for each machine that is supposed to render pdf files. Unless you’re operating the Wikipedia installation, one machine should suffice.
 * nslave pulls new jobs from exactly one mw-qserve instance and calls the mw-zip and mw-render programs in order to download article collections and convert them to different output formats. nslave uses a cache directory to store the generated documents. nslave also starts an internal http server serving the content of the cache directory.
 * postman uploads zip collections to Pediapress in case someone likes to order printed books. You should start one instance for each mw-qserve instance.

If that works you could keep starting your server like that but you can also create a shell script like  and place it on your desktop and add the following commands to the script: When you are using a print-on-demand service: If you then double click the script and press  your server should be up and running.

The "best" option is that the render server starts up automatically when Ubuntu boots. There is documentation on this but it was not tried or tested yet.

Test your server
To test if your render server is working enter the following commands in a terminal screen : This test will use the Formula, NK-33 & Jupiter pages on the English Wikipedia site for the render test but you can request any page you like. When a page consists of multiple words put the page name between brackets like "Jimi Hendrix". When the test is ready there should be a pdf file called  in the   directory of your user. Check if the pdf output is correct.

Setup the Collection extension
To enable the Collection extension on your wiki follow the instruction on the Collection extension page.

LocalSettings.php
Because you are running your own render server you have to let your Wiki know where to find the render server. This means you have to put some extra configuration parameters into LocalSettings.php

If you don't alter any of the defaults used by the Collection extension and your Wiki can be accessed from the Internet your pages will get rendered by the render server from PediaPress:  http://tools.pediapress.com/mw-serve/ .

Save books
If you grant users permission to save books you need to create a template. With this template it is possible to generate a book with "one click". :  [ Download PDF] When users save books they will then be placed in.
 * with the following content:

Conditional inclusion of content
You can add functionality to your Wiki that will show or hide content. This means you can prevent content on your Wiki to be printed or the other way around where it will only show up on the printed output and not on your Wiki. You need to create two templates and add some code to your local  :
 * with the following content:
 * with the following content:
 * In :

An example,  or.

Pdf output style
When your render server is working it will use the default style for the pdf output. The default style options are loaded via. If you are happy with the default setup you can leave things alone but if you want to change page breaks, footers and other stuff you should create a python script called. It is possible to hack  but creating   is a better option then hacking. When there are updates  could get overwritten and you loose your changes. You can open  to check what parameters can be set up so you know what to put into. Both files are located in. To create  open a terminal screen and copy & past the following code into the terminal screen and press enter:
 * 1) Copy and past the example code below into the document and press save:
 * 1) Copy and past the example code below into the document and press save:

''It is very easy to break things when the content of  is not correct. In the example above the render server will look for  but that image will most likely not exist in that location on your render server. When you have created a book with a title page the faulty name will break the pdf rendering process. If you are testing different options and settings make sure to do this step by step, look (read) on your render server what is happening and check the pdf output in-between so when things are not working you "know" what caused the problem.''

Math formulas
When you use math formulas on your wiki and you have set up your render server to render the formulas you might have noticed that the quality (resolution) of the formulas in not "stellar". Not sure how the render server from PediaPress is set up but it renders formulas with higher quality then the "default" render server documented on this page. If you use the MathJax extension you will be especially "disappointed" because it renders very high quality formulas in your browser, compared to the formulas rendered with the Math extension.

To get the pdf result below the following set up is used in the  for mwlib:

It is possible to increase the quality of the pdf rendered formulas because PediaPress also does it. I did not find any documentation on how to do this so maybe somebody else has ideas on this subject.