MoinMaster: InstallDocs

About MoinMoin

MoinMoin is a full-featured wiki engine (a wiki engine is software that enables you to run a wiki).

For a more detailed description, please see the MoinMoin Homepage and the HowTos.

Skip to:

Installation Requirements

Before you start installing MoinMoin, some requirements have to be met. The actual requirements depend largely on what kind of setup you plan for your wiki installation.

What do you need to know?

There are two major ways of using MoinMoin, requiring different knowledge about the environment it is going to be installed in (e.g. operating system, server softwares, etc.):

  • Quick installation:
    • A likely scenario for personal use on a PC or Notebook
    • (!) No knowledge about administration of servers is required

    • You should be familiar with your chosen operating system
  • Server installation:
    • General server administration knowledge is required
    • You have to know about web server configuration
    • You have to know about permissions, users, groups and the like

(!) Please note, that there are service providers who offer hosted, pre-configured MoinMoin installations.

What software do you need to have installed?

The software that has to be installed on the target machine, also largely depends on the type of deployment AND on the features you want to make use of. While the largest amount of functionality in MoinMoin works with a minimal set of requirements, some features can only be activated in the presence of additional software:

Required software

All installations

As MoinMoin is written in Python, you need Python! :)

  • We recommend using Python 2.4.x or 2.5.x, if possible.
  • Python 2.6.x should also work, but is less tested.
  • /!\ Python 3.x (or Python older than 2.4) will not work for MoinMoin.

Quick Installation

No web server is required (the wiki runs on a builtin server).

Server Installation

  • A webserver of your choice, for example:
  • A web server protocol extension to speed up the serving of the wiki:
    • WSGI: very fast and standardized protocol for serving Python web apps (strongly recommended), available for

      (!) MoinMoin is a WSGI application, thus using a WSGI web server is the most direct way to run MoinMoin.

    • FastCGI: also quite fast, available for

    • SCGI: similar to FastCGI, available for

      • Apache (mod_scgi) or

      • lighttpd (builtin)
    • AJP: another fast exchange protocol, mostly found in setups involving also an Apache Tomcat Java server.

  • In the absence of such a protocol extension, you can always run MoinMoin as a CGI script, but keep in mind, that:

    • CGI is very slow and

    • perhaps unsuited for larger public wikis.

Optional services

Optional you may need the following configured services to make use of extended features of your wiki:

  • SMTP mail server: (or working sendmail command) for sending out email notifications

  • Jabber server: for notifications via Jabber/XMPP

  • procmail-like mechanism: for importing emails into the wiki

Optional software

Following is a list of software required for special features:

  • xapian libs with python bindings: Xapian indexed search

    • antiword, catdoc: indexing MS word/excel documents

    • xpdf-utils: indexing PDF files

  • python-xml (PyXML): gui editor, docbook

    • if you use Python 2.5.1 or newer, you don't need to install python-xml.
  • docutils: parsing reStructuredText wiki pages

  • gdchart: nice charts for statistics

  • openid libs: authentication with OpenID

  • python-ldap: authentication against a LDAP directory

  • MySQLdb: authentication against a MySQL database

  • docbook xslt files: parsing docbook wiki pages

  • 4suite: needed for extended XML/XSLT parsing

Quick Installation: The 1 minute MoinMoin install

If these steps were not verbose enough for you, you can try one of these more detailed instructions:

Linux: Detailed Quick Installation

Download MoinMoin

Please read the MoinMoinDownload wiki page to find and download the latest MoinMoin release version.

(!) Please remember the path where you saved that download and also its exact filename.

The filename will be likely something like moin-1.9.0.tar.gz (for moin version 1.9.0), but we will just talk of moin-x.x.x because the concrete version number changes often. You have to use the real version number in the commands you enter, not x.x.x, of course.

Working on the shell

For the next steps, we will work on a shell prompt (for sure you can also do all the steps using some GUI tool of your favourite desktop environment, but because of the diversity of those environments, you will have to find out the right tools yourself using these steps as a guideline).

(!) If you use some graphical desktop environment or some X Window Manager, you will first have to get some terminal window (usually called "Terminal", "XTerm", "shell", "bash", "Command line window" or similar). Start it. If you see something showing a $ and a blinking cursor right of it, it worked. We call this window "shell" from now on.

/!\ Note that you must not use a "root shell" for this type of installation. Just use a shell as the non-priviledged user you usually log in as. You can use the id command to display what user you are and it must not display "root".

For the next steps, we assume you have downloaded the moin archive into your home directory and that the current directory is your home directory (that's the default when you start a shell, usually indicated by a shell prompt showing ~$ - the tilde means you are in your home directory and the dollar means that you can enter a command right of it).

Verify the integrity of your downloaded file

After you downloaded it, make sure the download was working correctly by verifying the md5sum (a checksum) of the archive:

$ md5sum moin-x.x.x.tar.gz

The value (XXX...) md5sum shows left of the filename must match the value we published on the download page for the file you just downloaded!

/!\ If it does not match, your download is corrupted somehow. Remove the file and try downloading it again.

Unpack MoinMoin

We use a gzipped tar archive for our release archives - you need to unpack it before using.

Unpack it using this command on the shell:

$ tar xvzf moin-x.x.x.tar.gz
(it will show a long list of all files it has unpacked)

This will create a directory moin-x.x.x in the current directory with all the MoinMoin release files in it.

Run MoinMoin

MoinMoin is written using the Python programming language, thus you need to start it using the python interpreter:

$ cd moin-x.x.x
$ python
(you will see the log output of the running MoinMoin server here)

After MoinMoin has started, it will show some log output in your terminal window. Within that logging output, it will also announce on which IP address and port the server runs (

Now just leave that terminal window as it is - the builtin web server of MoinMoin will work as long as you don't stop it.

You can stop the server by closing that terminal window or by pressing Ctrl-C to interrupt it.

Use MoinMoin

Just point your web browser at the address you got from the terminal window (e.g.: or http://localhost:8080/ ).

You should now see your fresh moin wiki in your browser, maybe bookmark that address so you don't have to enter it manually each time you use your wiki.

Your wiki is ready to use now. Have fun! :)

Mac: Detailed Quick Installation

Apple's Mac operating system comes with Python already installed as a part of the core system software, making running Moin wiki very easy.

Download MoinMoin

  1. Download the latest Moin from MoinMoinDownload page.

  2. Double-click to expand.

Starting Moin for the first time

By default, python scripts (.py) will open in For convenience, we'll want to associate .py files to open in so that we can simply double-click the file to run Moin.

  1. Right-click (control-click) on the file.

  2. From the contextual-menu,
    1. select "open with..." > "Other...";

    2. from the file dialog; select "All Applications", check "Always Open With", and then navigate to (located in //Applications/Utilites/).
      (The "Always open with" sets as the default application, so in the future you can double-click the file).

Daily Use

  1. double-click on the file, will launch.
  2. Point your browser at http://localhost:8080

  3. To quit the wiki, simply close the terminal window.

Windows: Detailed Quick Installation

Download & Install Python

Moin relies on Python, which requires a separate install on Windows.

  • Go to: and download the Python installer.

  • Run it!
    • If you want to save some space, you can unselect all but the first two options.
    • The installer will automatically associate .py files with Python.

Download & Expand Moin

  1. Download the latest Moin from MoinMoinDownload page.

  2. Expand using 7-zip or similar.

  3. Simply double-click in the Moin folder.

Daily Use

  1. Double-click on the file, a black commandline window will open.

  2. Point your browser to http://localhost:8080/

  3. To quit the wiki, simply close the terminal window.

Server Installation

How to setup MoinMoin for various webservers / gateway interfaces.

Please note that we require server admin experience for a server installation. It is not in the scope of this documentation to teach you (web) server configuration, but just to show how MoinMoin is installed. If you are unsure about your experience level, please try the Quick Installation first.

MoinMoin and WSGI

MoinMoin is a WSGI application. Therefore the best environment to run a MoinMoin instance in, is a WSGI-aware one. Here are some of them:

Also we will cover some legacy deployment methods for serving MoinMoin from non-WSGI-aware setups. The needed adapters are included in the MoinMoin distribution.

  • CGI: the classic among web application serving, awfully slow but works (almost) everywhere.

  • FastCGI / SCGI / AJP: fast and in the case of FastCGI quite widespread.

Apache with mod_wsgi

We won't go into the details of how to install mod_wsgi or Apache. Follow these instructions to setup mod_wsgi. If everything has been configured to your liking, you can test your setup with the application contained in test.wsgi (please read the hints included in the file).

Some further hints for usage of mod_wsgi:

  • If possible, use mod_wsgi's daemon mode (not the embedded mode). This can prove more secure, since it seperates the WSGI apps from the actual Apache process.

  • If you use Windows, there is no daemon mode, thus you have no other choice than to use embedded mode.

  • If you use Debian Etch, there is a mod_wsgi backport available on

MoinMoin specific installation

MoinMoin installation

You may, but you do not need to, install MoinMoin to system specific locations via the use of

(!) You can place the MoinMoin package (a directory called MoinMoin/ containing most of the code) anywhere you like, no specific location in the filesystem is required.

If you choose to use, you can install MoinMoin using:

python install --force --record=install.log --prefix='/usr/local'
# or alternatively, to the default system location:
python install --force --record=install.log
# --force is important, without it might not overwrite outdated files at the destination

/!\ Please note that using like shown above will overwrite all files at the destination. So if you modified files there, your modifications will be lost. It won't remove outdated files there, though, so if you had used before for the same destination, maybe clean up at the destination before installing a new moin version.

(!) If you need to modify files, do not do that at their original place, but copy them to some safe place first and then edit them there.

The file install.log will contain a complete log of installed files. You may want to keep it in case you have trouble to locate some file(s) we are talking about below.

Python path setup

Code: From here on we will use /moin/code to refer to the parent directory of the MoinMoin/ package directory.

Config: You can place the wiki config files (they are just Python code) anywhere you like, no specific location is required. We will use /moin/config to refer to the directory that contains your wiki config files.

To make MoinMoin and Python find the needed files, you need to make those locations known:

  • Python needs to be able to find the MoinMoin code package - this is needed so that from MoinMoin import ... can work. ((!) This is not needed if you choose to do a system-wide installation.)

  • Python needs to be able to find the wiki configuration files - this is needed so that moin is able to import your wiki config files.

For this to work, you can simply edit moin.wsgi (or in case you deploy with CGI/FCGI/etc. the particular example from wiki/server). There is already example code in those files, just remove the comment (# hash character) and change them accordingly:

sys.path.insert(0, '/moin/code')
sys.path.insert(0, '/moin/config')

You can place moin.wsgi anywhere you like. Just make your web server find and use it.

MoinMoin wiki configuration

Although the code is now ready to run, your wiki is not configured yet.

You now have to create your wiki configuration within the /moin/config/ directory.

Single wiki

Just copy the file wiki/config/ from the distribution archive to /moin/config/.

The file is thoroughly commented to ease you through the configuration. Be sure that if you configure paths in the file, that those paths are absolute paths. This way you ensure that the needed files are definitely found and save yourself some troubles. The essential configuration directives are:

  • data_dir: this should point to where the particular data of your wiki should be stored. (see below)

  • data_underlay_dir: MoinMoin comes with (pre-made) system and help pages. This directive should point to the directory where you put those (see below)

  • interwikiname: This should be a short descriptive identifier for your wiki. It needs to be unique and should never be changed later

  • sitename: This will be the name of your wiki for display purposes

/!\ We don't require any specific file system locations, but please be careful: data_dir contains sensitive informations that must not be read by anything or anyone except the running moin wiki code. For example, you must not make data_dir accessible directly via the webserver, thus you must not copy them to a directory below document root of your webserver. Any other permanent storage location on a fast local filesystem will be fine.

You need to copy the complete contents of the wiki/data/ directory we provide in the distribution archive to the location you specified as data_dir. The same goes for wiki/underlay/ and the location you specified as data_underlay_dir.

Multiple wikis

Just copy the files wiki/config/wikifarm/* from the dist archive to /moin/config/.

Now follow the directions as for a single wiki (see above) for each of your farm wikis.

Special wiki farm hints:

  • you need a separate data_dir and data_underlay_dir per wiki

  • if you want to share some settings for your wikis, put them into - they will be inherited by mywiki

  • the settings that need to be different are put into

  • if you need more than 1 wiki, add files like and reference them from as you see for mywiki

Static file serving

MoinMoin also comes with some static files like images, CSS, Javascript, Java applet files, etc. (see the MoinMoin/web/static/htdocs/ directory in the distribution archive). They are needed for things like styling, icons and additional client-side functionality.

MoinMoin serves those files by a builtin static file server at the path '/moin_staticXYZ' (XYZ like in MoinMoin version X.Y.Z, e.g. /moin_static190 for moin 1.9.0).

Please note that this path is relative to the script root, so:

  • if you run your wiki script at /mywiki, the URL for the static files server will be /mywiki/moin_staticXYZ. You need to configure url_prefix_static in your wiki config to match this.

  • if you run your wiki script at /, the URL for the static files server will be /moin_staticXYZ - and it will automagically match the default value of url_prefix_static, so no need to configure it).

Running MoinMoin with mod_wsgi

Now you should be able to simply run the moin.wsgi script the same way you ran test.wsgi above. You can test if everything works by following these steps:

  • Access the URL you have configured for your wiki and you should see something

    looking similar to the MoinMoin homepage.

  • Go to the WikiSandBox page in your wiki.

  • Try to edit it and save your changes.
  • If that works, see if your edit is shown on the RecentChanges page.

  • If you see them, congratulations, your new wiki works! :)

Running MoinMoin with CGI, FastCGI, SCGI or AJP

If you are not running a WSGI capable server and want to deploy MoinMoin with one of the other methods (like CGI, FastCGI, SCGI or AJP), just use the appropriate script for the desired method from wiki/server/ (instead of moin.wsgi):

  • moin.cgi: serves both CGI and FastCGI requests.

  • moin.scgi: serves SCGI capable servers

  • moin.ajp: serves AJP capable servers

Now edit that script (similarly as shown above for moin.wsgi) to make python find the moin code and wiki configuration files.

For setting up your particular webserver to speak any of these protocols to the moin application please refer to the webserver's documentation.

/!\ When using the scripts for FastCGI, SCGI or AJP (not CGI), be aware, that they can also act as externally spawned processes to the webserver. Via the means of commandline parameters they can be bound to an interface or UNIX socket and also do threading or forking for performance.

Try running moin.cgi --help to get an example. When run without any options by the webserver, control of sockets and the like is left to the webserver.


When things go wrong and reading the docs does not help, just:

  • ask concrete questions on the MoinMoinChat

  • and wait until someone answers

MoinMaster: InstallDocs (last edited 2009-02-15 21:33:36 by anonymous)