Management of MoinMoin wikis for beginners

Rationale for this page: The official and unofficial MoinMoin documentation pages are sadly difficult to use when you need to do standard system administration tasks, such as configuring and upgrading a MoinMoin wiki. Answers to simple beginner's questions are often extremely difficult to find, and you may spend hours googling for them. Therefore we have collected the information below in order to provide an overview for MoinMoin beginners with pointers to the information on the web. This page has also been copied into http://moinmo.in/HowTo with the title Management of MoinMoin wikis for beginners.

Caveat: This information pertains to a Linux operating system with an Apache web-server. We use RedHat RHEL5 Linux on our server.

Contact info: Comments on this page are welcome ! Send mail to Ole.H.Nielsen at fysik.dtu.dk.

Download and install

The MoinMoin wiki software can be downloaded from the MoinMoin Download page and it should be installed as explained in the Getting Started section of that page. We currently use MoinMoin version 1.8.8.

We follow http://coq.inria.fr/cocorico/HelpOnInstalling/BasicInstallation and install MoinMoin to the default system location:

tar xzf moin-1.8.8.tar.gz
cd moin-1.8.8
python setup.py install --record=install.log

Some Linux distributions also have a moin RPM, however, these tend to be very much out of date (and therefore lacking security patches) and cannot be recommended (for an example see RPMforge).

moin command

The installation creates just one user-level Moin command:

/usr/bin/moin

Run /usr/bin/moin with no arguments to see the usage information. There is also a page with Help on Moin Command.

There are two important arguments to moin:

  • --config-dir: Path to the directory containing the wiki configuration files. [default: current directory]
  • --wiki-url: URL of a single wiki to migrate e.g. http://localhost/mywiki/ [default: CLI (the actual meaning of the term "CLI" in this context remains a mystery so far)]

See also the source code file /usr/lib/python2.4/site-packages/MoinMoin/script/__init__.py.

To get moin syntax help use:

moin <module> <subcommand> --help

Documentation of MoinMoin

About MoinMoin (Wikipedia article).

There are some MoinMoin HowTos and a list of Help pages.

You can also use the built-on Moin HelpContents pages (from the underlay/ pages).

There are some MoinMoin mailing lists, especially the Moin-user list.

The MoinMoin IRC chat.

Supplementary third-party documentation of MoinMoin which we find useful:

Configuration of MoinMoin

We assume from now on that the Moin configuration files will be in:

/var/www/wiki

This directory must be owned by user apache so that the web-server can write compiled Python .pyc files:

chown apache.apache /var/www/wiki

Data directories

The Moin wiki data must be kept separate from the Apache webserver directories for security reasons, see Security warnings in http://coq.inria.fr/cocorico/HelpOnInstalling/WikiInstanceCreation

We shall keep data directories in:

/var/moin

The data files must be owned by user apache (so they can be changed), so it may be necessary to do:

chown -R apache.apache /var/moin/*

in case some files do not have the correct ownership.

If your system has SELinux enabled and enforcing, you probably need to change the SELinux file context of the MoinMoin pages:

chcon -R -t httpd_sys_content_t /var/moin

We can rsync this directory from another server if we want to copy the wiki to another server (also for MoinMoin mirror servers, see below), and thereby all pages and users are copied over automatically.

Underlay directories (Help pages)

The underlay/ directories are used for shared read-only system and help pages. In every MoinMoin wiki provides you with the HelpContents pages. You probably want to share the underlay/ directories between all of the wikis in your wiki farm (see Farm configuration).

Copy MoinMoin's installed underlay/ directory to another location, and make sure the files are owned by user apache:

cp -rp /usr/share/moin/underlay /var/moin/
chown -R apache.apache /var/moin/underlay/
MoinMoin version 1.9 Help pages

MoinMoin version 1.9 comes with no system and help pages installed by default! You can only see the LanguageSetup page, see also http://master19.moinmo.in/LanguageSetup

First you must install the underlay/ directories as shown in the preceding section. Then install the help pages that you want in the languages you want, as instructed in the LanguageSetup page (you must do this in the Wiki, it can't be done on the command line):

  1. Define a superuser in farmconfig.py.
  2. Log in as that superuser.
  3. Go to the LanguageSetup page link install help and system page packages.
  4. Select language and install just the help pages you need.

    Quickstart (for lazy people): Install the package all_pages for the language(s) in which you provide some content.

  5. Undefine the superuser again (for security reasons) - optional ?

Farm configuration

A Farm is a set of independent Wikis running on the same server. The farm configuration is made in the file:

/var/www/wiki/farmconfig.py

When upgrading Moin, back up the current configuration first, then the new farm template file farmconfig.py should be copied from the new MoinMoin installation:

cd /var/www/wiki
cp -p farmconfig.py farmconfig.py.BAK
cp /usr/share/moin/config/wikifarm/* .

The farmconfig.py should then be reconfigured with the relevant settings from the older farmconfig.py.BAK.

You must define a shared underlay/ directory for all Moin wiki farms in farmconfig.py by pointing to the underlay/ directory (see Underlay directories (Help pages):

data_underlay_dir = '/var/moin/underlay/'

For the farm's Wiki instances, check that the correct URL pattern is used in the lines with wikis, for example:

wikis = [
    ("it",  r"^wiki.example.com/it.*$"),
]

Note: With MoinMoin version 1.9 and above the syntax is slightly different:

wikis = [
    ("it",  r"^https://wiki\.example\.com/it.*$"),
]

Creating or adding a new Wiki

If you create a new Wiki, say XXX, from scratch, or if you want to add an extra Wiki instance to an existing farm of Wikis, there are instructions in http://coq.inria.fr/cocorico/HelpOnInstalling/WikiInstanceCreation

Use the file mywiki.py (copied from /usr/share/moin/config/wikifarm/) as a configuration template:

cp mywiki.py XXX.py
chmod 644 XXX.py

Remember to add a new ScriptAlias to the Apache configuration files, and add the instance to farmconfig.py.

Start by copying the templates directories:

mkdir /var/moin/XXX/
cp -rp /usr/share/moin/data /var/moin/XXX/
chown -R apache.apache /var/moin/XXX

where XXX is the Moin instance directory.

Restructured text (docutils)

This is an optional step: Restructured text is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. The docutils Python package must be installed if you want to enable Restructured text markup in the MoinMoin pages:

  1. One way is to install an RPM from you distribution:

    yum install python-docutils
  2. Another way is to install from source: Unpack the docutils source tar-ball and install:

    tar xzvf docutils-0.X.tar.gz
    cd docutils-0.X
    python setup.py install

In order to enable Restructured text markup in the pages, define this in the XXX.py farm configuration files:

# Use Restructured text as default markup
default_markup = 'rst'

One feature of Restructured text that's poorly documented is how to link to attachments in the page. This is done by the double-underscore like in this example:

Migration of data is described in the *MoinMoin* file moin-VERSION/docs/README.migration__.

__ attachment:README.migration.txt

A scant documentation of this is in http://moinmo.in/HelpOnParsers/ReStructuredText section Support for MoinMoin-specific link schemes.

Wiki navigation bar

Moin contains a number of Wiki navigation tabs (the look depends on the theme chosen). This is configured in the wiki instance file XXX.py by the navi_bar list, for example:

  navi_bar = [
    # Will use page_front_page, (default FrontPage)
    u'%(page_front_page)s',   # Wiki front page
    u'Linux',                 # An important topic...
    u'Windows',               # Another important topic...
    u'RecentChanges',         # Lists recently changed pages
    u'FindPage',              # Search page
    u'HelpContents',          # Help page
]

If the navi_bar doesn't work, for example HelpContents is not available, and you are using MoinMoin version 1.9 and above, please see the section MoinMoin version 1.9 Help pages regarding installation of help pages.

User configuration

Users can create accounts by themselves on the Wiki Login page, see also Help on Login.

The procedure for creating a new account is:

  1. The user goes to the Wiki page in question and clicks on the Login link near the top of the page. This takes you to a page ...?action=login.
  2. Click on the link If you do not have an account, you can create one now.
  3. On the Create Account page, enter:

    1. Your Wiki username, by convention FirstnameLastname.
    2. Your password of choice (not a very secret password, it may not be safely stored!).
    3. Your E-mail address (for MoinMoin sending mail to the user, for example for password recovery).
    4. Press Create Profile.

MoinMoin stores a permanent cookie in your browser so the user will remain logged in.

There does not seem to be a MoinMoin interface to the Linux PAM authentication modules, so there doesn't seem to be any way to use Linux system username/password accounts.

Administrators can manage user accounts in MoinMoin, please see http://moinmo.in/HelpOnUserHandling. The moin command has some user handling subcommands, see the syntax by:

moin account check --help
moin account create --help
moin account disable --help
moin account homepage --help
moin account resetpw --help

User Groups and Access Control Lists

Access Control Lists (ACL's) allow you to control the permissions of a user or a group of users (which you define, see HelpOnGroups). You can define permissions for the entire wiki, or for select pages of the wiki.

A MoinMoin group is a simple data structure that maps a group name to a set of group member names. It can be used e.g. within ACL definitions to specify groups of users.

You should make a page called AdminGroup and use it to define some people who get admin rights. The AdminGroup has the format:

#acl AdminGroup:read,write,revert All:read
#format wiki
Members of this group will get admin rights. If you think you should be in this group, contact one of its members to add you.
* SomeAdmin
* AnotherAdmin

Notifications

MoinMoin can notify users of changed pages by E-mail, see Help On Notification. Users can click on the User menu item Settings to manage their notifications.

Cleanup of pages

After some time there may be empty pages, deleted pages, or pages that are no longer referred to. There is a cleanup command for this:

moin maint cleanpage --help

which makes some shell commands (please review the commands in clean.sh) to move bad pages out of the way:

cd /var/moin/XXX
mkdir trash deleted
moin --config-dir=/var/www/wiki --wiki-url=wiki.example.com/XXX maint cleanpage > clean.sh
sh -x clean.sh

Upgrading MoinMoin

Migration of data is described in the MoinMoin file moin-VERSION/docs/README.migration.

The wiki pages are accompanied by a meta file (not to be changed manually!) which described the MoinMoin version of all the pages:

cat /var/moin/XXX/data/meta
data_format_revision: 1090300

There exists further advice about upgrading MoinMoin:

MoinMoin version

It is not immediately obvious which version of MoinMoin is installed on a system.

One way to inquire about the installed version of MoinMoin is to show the Wiki's SystemInfo page. See MoinMoinQuestions/Other question What version of MoinMoin is installed on my PC?

Another way is using the moin command:

moin --version
MoinMoin 1.8.8 [release]

A third way is to look into the installed file /usr/lib/python2.4/site-packages/MoinMoin/version.py.

If your MoinMoin has been installed by RPM, you can of course also do rpm -q moin.

Upgrading from version 1.8 to 1.9

The MoinMoin configuration files in version 1.9 differ somewhat from version 1.8. As always, the old farmconfig.py and wiki files XXX.py should be reconfigured with some relevant settings from the older version backups.

Even though the MoinMoin 1.9 documentation recommends to use Apache with WSGI (see Apache configuration scripts below), the old and slow moin.cgi works as well. Make a backup first:

cd /var/www/wiki/cgi-bin
cp -p moin.cgi moin.cgi.BAK

before installing the moin.cgi from version 1.9 and configuring it as shown in Configuration of MoinMoin.

Next steps:

  1. Install MoinMoin version 1.9.X as usual (see Download and install).

    You will have to modify the wikis list in farmconfig.py for version 1.9 like in Farm configuration.

  2. Perform page cleanup and migration as shown in the following section for upgrades to version 1.8.X, but with the new URL syntax:

    moin --config-dir=/var/www/wiki --wiki-url=https://wiki.example.com/XXX maint cleancache
    moin --config-dir=/var/www/wiki --wiki-url=https://wiki.example.com/XXX migration data

Upgrading from version 1.5.3 and above to version 1.8.X

Before an upgraded version of MoinMoin is installed, the old installation must first be removed (unless you used an RPM package). Before the above manual installation do:

mv /usr/lib/python2.4/site-packages/MoinMoin /usr/lib/python2.4/site-packages/MoinMoin.<old-version>
mv /usr/share/moin /usr/share/moin.<old-version>
mv /var/moin/underlay /var/moin/underlay.<old-version>

If you are upgrading pages from an older version of Moin, you need to copy both the pages/ directory as well as the file meta, which contains information about the pages' version of Moin:

/var/moin/XXX/data/pages/
/var/moin/XXX/data/meta

Some clarifications of the upgrading advice are required. First, the command python MoinMoin/script/moin.py maint cleancache must in reality be done as with the /usr/bin/moin command:

moin --config-dir=/var/www/wiki --wiki-url=wiki.example.com/XXX maint cleancache

for each wiki instance XXX listed in farmconfig.py.

Now run the Moin 1.5.3 (and above) migration script:

moin --config-dir=/var/www/wiki --wiki-url=wiki.example.com/XXX migration data

which will display instructions and generate a changes-file /var/moin/XXX/data/rename1.txt. If this command gives any error messages, it may be because some unexpected files exist in the directory tree (for example, backups from some editors). You must use the error message to locate the unwanted files and remove them, and then rerun the moin command until it runs without errors.

Review and edit /var/moin/XXX/data/rename1.txt. One important notice is that pages with a blank in the page name will have all blanks replaced by underscores. The links in the pages may not be updated by this procedure (at least for our pages written in the reStructured text markup, and it seems that manual editing of the migrated pages must be done afterwards.

When you think the changes are OK, then rename the file:

mv /var/moin/XXX/data/rename1.txt /var/moin/XXX/data/rename2.txt

and rerun the above moin migration data command.

A new MoinMoin version presumably has updated underlay/ directories, so you should remove remove the old underlay/ directories and copy the new ones as explained in the Underlay directories (Help pages) section.

In order for the Apache web-server to read and write data files, they must be owned by user apache, so do:

chown -R apache.apache /var/moin/*

Also, the MoinMoin static files URL Alias /moin_staticVVV in the Apache configuration file must be updated according to the new version VVV of MoinMoin. Annoying, it would be better if there was a non-changing URL :-(

Upgrading from version 1.5.2 or older

If the old pages are from Moin version 1.5.2 or older, you must read the MoinMoin file moin-VERSION/docs/README.migration. This describes also migration from even older versions of moinMoin.

Before migration from 1.5.2, check that you don't have any incorrect file meta which would refer to a newer version of MoinMoin (version earlier than 1.5.3 do not have a meta file)

/var/moin/XXX/data/meta

For Moin 1.5.2 you need to migrate to 1.5.3 by:

cd /usr/lib/python2.4/site-packages/MoinMoin/script/old/migration
python 152_to_1050300.py /var/moin/XXX/data/

for each wiki instance XXX. This will create a new version information file /var/moin/XXX/data/meta.

After upgrading to 1.5.3, you can do further upgrades by the standard method described above.

Apache web-server setup

There is some advice at http://coq.inria.fr/cocorico/HelpOnInstalling/ApacheOnLinux.

Apache scripts

The CGI script is the simplest and slowest way to implement a MoinMoin server. The MoinMoin people recommend to use faster methods such as FastCGI or WSGI (see http://master19.moinmo.in/InstallDocs#server). See also http://coq.inria.fr/cocorico/HelpOnInstalling/ApacheOnLinux and the Apache configuration section below.

To use the simple CGI scripts, copy the Moin CGI file into the web-server directories:

cp /usr/share/moin/server/moin.cgi /var/www/wiki/cgi-bin/moin.cgi

As explained in the help page, add the following line to moin.cgi which points to the location of Wiki files like farmconfig.py:

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

One should use absolute paths in stead of relative paths.

Apache configuration

First ensure that the required Apache packages are installed:

rpm -q httpd mod_ssl

This is our Apache configuration file /etc/httpd/conf.d/wiki.conf for the Wiki (must change the server address):

# Wiki
<VirtualHost XX.YY.ZZ.VV:80>
    AddDefaultCharset Off
    ServerAdmin webmaster@example.com
    ServerName wiki.example.com
    Redirect / https://wiki.example.com/
</VirtualHost>

# Wiki SSL
<VirtualHost XX.YY.ZZ.VV:443>
    AddDefaultCharset Off
    ServerAdmin webmaster@example.com
    ServerName wiki.example.com
    DocumentRoot /var/www/wiki/

    # For MoinMoin version >= 1.9
    # Static moin files for v.1.9.3, URL changes with Moin version:
    Alias /moin_static193 "/usr/lib/python2.4/site-packages/MoinMoin/web/static/htdocs/"
    # Required for /wiki/modern/css/*.css files:
    Alias /wiki/ "/usr/lib/python2.4/site-packages/MoinMoin/web/static/htdocs/"

    # For MoinMoin version <= 1.8
    # Static moin files for v.1.8.8, URL changes with Moin version:
    # Alias /moin_static188 "/usr/share/moin/htdocs/"
    # Required for /wiki/modern/css/*.css files:
    # Alias /wiki/ "/usr/share/moin/htdocs/"

    ScriptAlias /it "/var/www/wiki/cgi-bin/moin.cgi"
    SSLEngine On
    SSLCertificateFile /etc/pki/tls/certs/example.com.crt
    SSLCertificateKeyFile /etc/pki/tls/private/example.com.key
</VirtualHost>

Here moin_static188 must be changed according the the Moin version being used !

The IP address in the configuration file must be changed according to which server is used. Also, SSL certificates must be installed (beyond the scope of this page).

Logging

Moin will make logging in the Apache logfiles by default. Some explanation of Moin logging is in /usr/share/moin/config/logging/ or in the source code moin-1.V.V/wiki/config/logging/. A thorough explanation of logging has not been found on the web so far.

Some example logging configurations are installed in the /usr/share/moin/config/logging/ directory, where we use the stderr example to make logging to the Apache webserver, changing however the loglevel in this file:

[DEFAULT]
# Default loglevel, to adjust verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL
loglevel=WARNING

The default logging level is INFO which is useful while installing/debugging, but for a production site WARNING is better.

The stderr logging is configured in the moin.cgi file:

# b) Configuration of moin's logging
#    If you have set up MOINLOGGINGCONF environment variable, you don't need this!
#    You also don't need this if you are happy with the builtin defaults.
#    See wiki/config/logging/... for some sample config files.
from MoinMoin import log
log.load_config('/usr/share/moin/config/logging/stderr')

MoinMoin mirror

This wiki can be mirrored on another server - all files in the /var/moin/ directory are rsync'ed by a crontab job every night:

10 0 * * * /usr/bin/rsync -aq /var/moin/ mirror:/var/moin/

Two configuration files must be modified so that the mirror wiki works and is read-only:

  • In /var/www/wiki/XXX.py the following line is changed from:

    acl_rights_before = u"AdminGroup:read,write,delete,revert,admin"

    to:

    acl_rights_before = u"AdminGroup:read"
  • The file /var/www/wiki/farmconfig.py must have the hostname configured as in:

    wikis = [
      ("it",  r"^mirror.example.com/it.*$"),
    ]

IT-wiki: MoinMoin_Wiki (last edited 2016-03-07 20:36:40 by OleHolmNielsen)