.. _mwlib-renderserver:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Running a renderserver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Overview
--------------
Running a renderserver consists in running multiple programs [#mw-serve]_.
Unless you have some special requirements, you should be able to start
a working renderserver by running the following commands::
$ nserve.py
$ mw-qserve
$ nslave.py --cachedir ~/cache/
$ postman.py
These programs have the following purposes:
nserve.py
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.
mw-qserve
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.py
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.py
postman uploads zip collections to pediapress in case someone likes
to order printed books. You should start one instance for each
mw-qserve instance.
None of the programs has the ability to run as a daemon. We recommend
using `runit `_ for process
supervision. `daemontools `_ is
similar solution.
Another alternative is to use `supervisor `_.
.. [#mw-serve] In mwlib prior to version 0.13 it was possible to get
away with running a single ``mw-serve`` program or even running no
program at all by using the mwlib.cgi script. These programs have
been removed in favor of the new tools, which provide the ability
to scale an installation.
nserve.py usage
----------------
nserve understands the following options:
``--port=PORT``
specify port to listen on. Default is to listen on port 8899 on any
interface.
``--qserve=HOST:PORT``
register qserve instance running on host HOST listening on port PORT
Any additional arguments are interpreted as additional qserve
instances to register.
The following command starts nserve listening on port 8000 using two
qserve instances::
nserve.py --port 8000 example1:14311 example2
mw-qserve usage
---------------
mw-qserve understands the following options:
``-p PORT``
specify port to listen on. Default is to listen on port 14311
``-i INTERFACE``
specify interface to listen on. Default is to listen on any
interface.
nslave.py usage
------------------
nslave understands the following options:
``--cachedir=CACHEDIR``
specify cachedir to use. this is where nslave.py will store
generated documents.
``--serve-files-port``
port on which to start the http server (default is 8898)
``--url=URL``
specify url under which the cache directory is being served. The
default is to compute this value dynamically.
``--numprocs=NUMPROCS``
allow up to NUMPROCS parallel jobs to be executed
postman.py usage
-------------------
postman understands the following options:
``--cachedir=CACHDIR``
specify cachedir to use. use the same value as specified when
calling nslave.py