Management of MoinMoin wikis for beginners
- Download and install
- Documentation of MoinMoin
- Configuration of MoinMoin
- User configuration
- Cleanup of pages
- Upgrading MoinMoin
- Apache web-server setup
- MoinMoin mirror
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.
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).
The installation creates just one user-level Moin command:
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
About MoinMoin (Wikipedia article).
You can also use the built-on Moin HelpContents pages (from the underlay/ pages).
The MoinMoin IRC chat.
Supplementary third-party documentation of MoinMoin which we find useful:
We assume from now on that the Moin configuration files will be in:
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
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:
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.
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/
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):
- Define a superuser in farmconfig.py.
- Log in as that superuser.
- Go to the LanguageSetup page link install help and system page packages.
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.
- Undefine the superuser again (for security reasons) - optional ?
A Farm is a set of independent Wikis running on the same server. The farm configuration is made in the file:
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.*$"), ]
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.
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:
One way is to install an RPM from you distribution:
yum install python-docutils
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.
Users can create accounts by themselves on the Wiki Login page, see also Help on Login.
The procedure for creating a new account is:
- 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.
- Click on the link If you do not have an account, you can create one now.
On the Create Account page, enter:
- Your Wiki username, by convention FirstnameLastname.
- Your password of choice (not a very secret password, it may not be safely stored!).
- Your E-mail address (for MoinMoin sending mail to the user, for example for password recovery).
- 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
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.
#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
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
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:
- Migration from moin 1.5 to 1.6 (and beyond) (Linux based)
- Updating from MoinMoin 1.5.x to 1.6.x (Windows based)
It is not immediately obvious which version of MoinMoin is installed on a system.
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.
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.
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.
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
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:
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 :-(
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)
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.
There is some advice at http://coq.inria.fr/cocorico/HelpOnInstalling/ApacheOnLinux.
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:
One should use absolute paths in stead of relative paths.
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 firstname.lastname@example.org ServerName wiki.example.com Redirect / https://wiki.example.com/ </VirtualHost> # Wiki SSL <VirtualHost XX.YY.ZZ.VV:443> AddDefaultCharset Off ServerAdmin email@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).
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')
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"
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.*$"), ]