Updating MoinMoin

General procedures

Download and unpack the new MoinMoin archive

Download the MoinMoin code that you are interested in updating to. If you are not a developer, this is usually the distribution archive for the latest released version from the project homepage.

Reading the docs

Please read the files docs/CHANGES and docs/README.migration contained in the moin distribution archive for details on what changed and how to upgrade.

The docs might contain import installation, compatibility and upgrade hints we won't repeat here.

Backup

Before you update an existing wiki, MAKE A BACKUP!

You have been warned, and it's not our fault when you end up like this: X-(

As you want to make a complete backup (not even losing a single edit), you want to stop your wiki server process now.

This is what you should backup (the real paths depend on your installation):

Code update

First remove the old MoinMoin code (including any *.pyc and *.pyo files).

If you are installing from the original distribution archive, run "python setup.py install" as root to install the new version.

If you are using some Linux (or other) distributor's package, please read their docs.

Please also upgrade your moin.wsgi (or other) server adaptor file. You likely have to edit it to fix some pathes and you also need to set some specific user/group/mode on that file (just look at the old one before replacing it).

Configuration update

After upgrading, your existing wiki should continue to work (the goal is to have sane defaults for any new config values, but then there can be bugs and also changes that must break compatibility).

Check that this is indeed the case, and then take the time to check the CHANGES file in your distribution archive. Often, new features will be invisible unless you extend your configuration in wikiconfig.py.

Check that you have the latest "intermap.txt" file; If you have your own entries, you can point "shared_intermap" at a file loaded before the file in your data directory, which takes precedence (i.e. have global entries in the shared one, private entries the data dir file).

Static files

Since release 1.9.0, moin has a built-in static file webserver to serve the CSS, images, javascript, etc. files that come with moin.

This static file web server serves the files contained in path MoinMoin/web/static/htdocs/ at URL <script URL> + <url_prefix_static>.

So, if you run your wiki at the root of your site (/) the default url_prefix_static will work for you.

The default url_prefix_static is something like /moin_staticVVV (VVV is 190 for moin release 1.9.0) and VVV will change on every release (moin 1.9.1 will use /moin_static191 by default). This is done to be able to use a very long cache lifetime for the static stuff, so your wiki will be faster and cause less load and traffic. Even if you don't use a long cache lifetime, a changing url_prefix_static makes sure that if you upgrade your wiki all your wiki users will immediately get the fresh static stuff.

If you run your wiki at a different base path, you need to set url_prefix_static to the correct value, e.g. url_prefix_static = '/mywiki' + url_prefix_static if you run your wiki at /mywiki.

If you want moin to serve a different directory than the default MoinMoin/web/static/htdocs/, you can change the path in moin.wsgi like shared='/my/path/to/htdocs' to serve static files from that path.

(!) Please note that if you serve the static files from a different than the "builtin" directory, you are responsible for updating those files from MoinMoin/web/static/htdocs/ when you upgrade your moin installation.

Alternatively to using moin's builtin static files server, you can also serve the static files with some external webserver (e.g. with Apache, if that is your main web server). If you want to do this, just have your web server catch the requests for stuff below the url_prefix_static URL (before they reach the moin script) and serve those requests with the files from MoinMoin/web/static/htdocs/ (or a copy of them).

Wiki pages update

System and Help pages

System and help pages are separately stored in the underlay directory. Just use the fresh underlay directory we provide in the distribution archive (move the old one to your backup directory) and read and follow the LanguageSetup page in your wiki.

If you previously modified some system page in your wiki (see EditedSystemPages on your wiki), you might want to Delete them to use moinmoin's updated version (warning: you can't un-delete that page later).

InterWiki data

Copy intermap.txt from the distribution archive into your wiki data

Your valuable own pages

See CHANGES and README.migration for maybe necessary steps to convert your data_dir to what we expect.

Clean your cache

Finally, stop moin, delete cached data by running moin ... maint cleancache, start moin.

Troubleshooting

Hints:

Version specific notes