HowTo: A MoinMoin wikifarm example on Ubuntu - by NicoZanferrari, January 2010

1. Preface

This tutorial will show you how to setup a simple wikifarm based on MoinMoin - with a couple non-rooted wikis inside. All the basic stuff should be faced, and everyone with a minimum knowledge of MoinMoin should be able to follow it. Use it as a working example, but don't forget the official documentation.

We'll use Ubuntu 9.10 Karmic Koala and MoinMoin (version 1.9.x) will use the Apache web server, with the recommended WSGI module. Suggestions and corrections are always welcome!

2. Installation

2.1. The requirements

The suggested requirements for MoinMoin on Ubuntu 9.10 are:

• apache2
• libapache2-mod-wsgi

Note that the officially suggested python-xml library is not anymore available in Karmic (see https://bugs.launchpad.net/ubuntu/+source/python-xml/+bug/343242). But it should not be needed anymore. Install them, for example, with a

sudo apt-get install apache2 libapache2-mod-wsgi

2.2. Install MoinMoin

Go to the download section on http://moinmo.in/ and download the latest release, moin-1.9.1.tar.gz at this time. Open a Terminal shell, go to the download folder and unpack it. Then install it with the default options:

cd moin-1.9.1
sudo python setup.py install --force --record=install.log

You can read more about --force option in the INSTALL.html file in the docs directory.

2.3. The WIKIFARM folder structure

I prefer to have all the management data and configuration in a single, easily accessible folder. So, in this HowTo we'll use the folder /wiki as the root and configuration directory of our wikifarm.

• FHS violation makes me sad panda. -- EugeneSyromyatnikov 2010-01-28 16:13:25

• I suggest either using /home/moin (and a moin uid/gid) or /srv/moin for the "single directory approach". -- ThomasWaldmann 2010-01-28 23:33:13

• /srv/moin follows FHS, keeps the data neatly organized, and simplifies backups of services on a given host. Similarly, making a place for tablespaces under /srv/db, virtual hosts in /srv/www/site/{fqdn}, and so on, makes filesystem layout more modular. -- PatrickJordan 2010-05-25 16:20:30

Under this /wiki folder, in this example there will be all the wiki instance folders.

We'll use two real instances called public and reserved. We'll also create a master wiki instance as /wiki/master to be cloned later, a /wiki/users, a /wiki/cache, and a /wiki/static folder.

2.4. Wikifarm creation

sudo mkdir -p /wiki/master # master wiki instance folder,  to be cloned later
sudo mkdir /wiki/users # where all the users data will be, in order to have unique pw and registration data
sudo mkdir /wiki/cache #  where all the cache and sessions data will be
sudo cp /usr/local/share/moin/config/wikifarm/farmconfig.py  /wiki/.
sudo cp /usr/local/share/moin/config/wikifarm/mywiki.py  /wiki/master.py
sudo cp /usr/local/share/moin/server/moin.wsgi /wiki/.
sudo cp -R /usr/local/share/moin/data /wiki/master
sudo cp -R /usr/local/share/moin/underlay /wiki/master
# static stuff like logos and themes will be placed here
sudo cp -Rp /usr/local/lib/python2.6/dist-packages/MoinMoin/web/static  /wiki/static
# create wiki instance folder and configuration from the master one
sudo cp -Rp /wiki/master /wiki/public
sudo cp /wiki/master.py /wiki/public.py
sudo cp -Rp /wiki/master /wiki/reserved
sudo cp /wiki/master.py /wiki/reserved.py
# fix security on folders
cd /
sudo chown -R www-data.www-data wiki
sudo chmod -R ug+rwX wiki
sudo chmod -R o-rwx wiki

2.5. Web server configuration

Edit /etc/apache2/apache2.conf and add at the end (or setup an include file if you prefer):

#
# MoinMoin WSGI configuration
#
# you will invoke your moin wikis like http://servername/public :
WSGIScriptAlias /public /wiki/moin.wsgi
WSGIScriptAlias /reserved /wiki/moin.wsgi
# create some wsgi daemons - use user/group same as your data_dir:
WSGIDaemonProcess moin user=www-data group=www-data processes=5 threads=10 maximum-requests=1000 umask=0007
# use the daemons we defined above to process requests!
WSGIProcessGroup moin
# setup an Alias for static stuff like logo and themes
Alias /wiki_static /wiki/static/htdocs

Note: the same WSGI file will be launched for every wiki instance.

If you are using moin 1.9.7, the last Alias should be: Alias /moin_static197 /wiki/static/htdocs

2.6. WSGI stuff

Edit /wiki/moin.wsgi and add at the end of the a2) paragraph the line:

sys.path.insert(0, '/wiki')

Note: the same /wiki/farmconfig.py program will always be launched for every wiki instance.

2.7. Wikifarm configuration

All of the common configuration for the wikifarm will be kept in the /wiki/farmconfig.py file. Comment out the line:

    ("mywiki", r".*"),   # this is ok for a single wiki

Change / add the lines:

wikis = [
    ("public", r"^https?://localhost/public.*$"),      # change localhost with your server's real name !!!
    ("reserved", r"^https?://localhost/reserved.*$"),  # change localhost with your server's real name !!!
]
    superuser = [u"WikiAdmin", ]
    # place these lines at the end
    url_prefix_static = '/wiki_static' # static stuff like logo and themes will be searched there
    tz_offset = 1.0 # default time zone offset in hours from UTC

2.8. Wiki instance configuration

For every wiki instance you have to modify the related /wiki/wiki_instance_name.py . In our example, in /wiki/public.py you should change / add:

    sitename = u'Public intranet Wiki of Example.com' # [Unicode] will be seen in the browser title bar
    interwikiname = u'PublicWiki' # [Unicode]
    data_dir = '/wiki/public/data/'
    data_underlay_dir = '/wiki/public/underlay'

You have also to change /wiki/reserved.py accordingly, like:

    sitename = u'Reserved intranet Wiki of Example.com' # [Unicode] will be seen in the browser title bar
    interwikiname = u'ReservedWiki' # [Unicode]
    data_dir = '/wiki/reserved/data/'
    data_underlay_dir = '/wiki/reserved/underlay'

2.9. Apply changes

Do a:

sudo /etc/init.d/apache2 restart

That's all for this basic wikifarm! Now open the browser an go to your root web page, like http://localhost/ . You can see that this is not modified at all, i.e. it's the "It works!" if you didn't have any previous web service:

But if you go to http://localhost/public you'll see the Welcome page for the public instance.

As you see this FrontPage is quite empty. But it's perfectly working - and you can improve it easily.

3. Basic improvements

• In both instances, create the superuser WikiAdmin and login. Then go to the subpage LanguageSetup, read it carefully and select the install help and system page packages link inside. Pick up your language(s) if different from English and install help and system pages (the last line with "all_pages" contains everything, but you should install at least the "essential system page" package). Your wiki instances will not be empty anymore.

• Your logo should be placed in the folder /wiki/static/htdocs/common, for example as example_logo.png. Then it will be shown in every page if you add to farmconfig.py the line:

    logo_string = u'<img src="%s/common/example_logo.png" alt="Example.com Logo">' % url_prefix_static

• you can move logging data (and configuration) under /wiki if you wish. Copy /usr/local/share/moin/config/logging/logfile as /wiki/log.config, and modify it with your needs. Activate it by changing the default logging values on /wiki/moin.wsgi.

• configure the Mail section already present on wikiconfig.py. Your users will be able to use the password reset feature and will be informed of changes on subscribed pages.

• play with Themes! Every user can change them, but the default one is specified in the theme_default parameter on wikiconfig.py. Take a look at http://moinmo.in/MoinMoinScreenShots for ideas and testimonials.

4. Big changes

4.1. Sharing authentication

If you use the wikifarm as an Intranet for a company or a school, it is normally not wanted to have different users / passwords for every instance. In this situation, you can add at the end of farmconfig.py the lines:

    user_dir = '/wiki/users' # user folder
    cache_dir = '/wiki/cache' # cache folder
    cookie_name = 'shared_wikifarm' # cookie name for shared authentication

(we have already created these two folders at the beginning).

After activating this configuration change, you better manually delete the name2id files under the cache folder. In our example:

sudo rm -f /wiki/reserved/data/cache/reserved/user/name2id
sudo rm -f /wiki/public/data/cache/public/user/name2id

They'll be automatically recreated when needed, but under the common /wiki/cache folder. Now, any existing user data are lost, so you have to re-create the WikiAdmin user. You can check that:

• user sharing is enabled. This means that if you create a user with a password in one wiki instance, it will be valid also for all the others.
• passed authentication is enabled. Therefore, your login credentials will still be silently accepted if you change the instance while logged on. And if you log out in one instance, you'll log out in all the others also.

The shared users and authentication can be setup just for some of your wikis. In this case you have to modify the specific configuration files instead of the common farmconfig.py.

4.2. Security of the instances

The two wiki instances we've created have same permissions, i.e. their pages are writable by everyone. A common simple change is to not allow anonymous users to change pages. In order to do this, add to /wiki/public.py the line (it's a single line, do not add any carriage return):

    acl_rights_default = u'WikiAdmin:read,write,delete,revert,admin Known:read,write,revert All:read'

Be careful to always remember about WikiAdmin user when you touch Access Controls Lists (ACLs). This simple modification will make all the pages of the public wiki instance writable only by logged-in users, but readable anonymously by everyone.

A more complex example is about having a group of users with different rights. For doing this, we have first to create a User Group and than modify the default user rights for that instance. Creating the User Group is quite simple: create a new page with a name that has some word ending with Group. Be careful that this group is visible only inside the wiki instance where it is created. So, for example, create a ReservedEditorGroup page in the reserved wiki instance:

#format wiki
These are people that are trusted to edit pages on the Reserved wiki instance:
 * JaneDoe
 * JoeDoe

Then add to /wiki/reserved.py the line (it's a single line, do not add any carriage return) :

    acl_rights_default = u'WikiAdmin:read,write,delete,revert,admin ReservedEditorGroup:read,write,delete,revert All:read'

This modification will make all the pages of the reserved wiki instance writable only by JaneDoe and JoeDoe, and readable by everyone. There is much more to say about access control lists (the official documentation will show you all the details), but this example should have given a simple idea to play with.

4.3. Activating the Xapian search engine

The Xapian search engine will improve a lot the search functions and speed. Also, it supports additional filters for file attachments. Install it with all the filters with a:

sudo apt-get install python-xapian antiword catdoc xpdf-utils

At the end of /wiki/farmconfig.py file add these lines:

    show_version = True # show moin's version at the bottom of a page
    show_timings = True # show some timing values at bottom of a page
    xapian_index_dir = '/wiki/cache/xapian' # Directory where the Xapian search indexex are stored
    xapian_search = True # True to enable the fast, indexed search (based on the Xapian search library)
    xapian_stemming = True # True to enable Xapian word stemmer usage for indexing / searching

Then, activate the changes as usual. Login as WikiAdmin and go to the SystemInfo page of one of your instance and you can see the line:

'''Xapian search'''
    Enabled, Xapian 1.0.15, index unavailable

This means that Xapian has been activated, but you must build your index for the first time for every instance. Execute:

sudo -u www-data moin --config-dir=/wiki --wiki-url=http://localhost/public index build --mode=rebuild
sudo -u www-data moin --config-dir=/wiki --wiki-url=http://localhost/reserved index build --mode=rebuild

You'll probably have some WARNINGs that the Xapian index does not exist, but you can easily resolve them by re-doing exactly the same commands. Please note that you must rebuild (--mode=rebuild) your index if you change at least one of xapian_index_history, xapian_index_dir or xapian_stemming configuration options!

Now, go to the SystemInfo subpage of one of your instance and you will see the line:

'''Xapian search'''
    Enabled, Xapian 1.0.15, index available, last modified: 2010-01-28 16:04:29

Also, make a test search within your instances - on the bottom of the result page you'll see Xapian search timings. ;-))

5. Suggestions

Small suggestions (help is welcome!):

• SECURITY: be careful that user passwords are not encrypted in the communication between the server and the client. This is not generally advisable, except for small intranet where you trust the network. In order to protect authentication data, the simpler solution is to use https for all the communication.

• SECURITY: you can use a separate moinmoin user for wsgi process (only the htdocs and moin.wsgi has to be accessible from the main apache)