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

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/

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 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. ================

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

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 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 /usr/share/moin/config/logging. 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 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')