moin for Debian
===============

Contents
--------

 1. Typical setup
 1.1 Example
 2. Upgrading from earlier versions of moin
 3. "Moin ... <command>"
 4. Always use farmconfig
 5. Additional notes
 6. Optional Features

1. Typical setup
----------------

This Debian package has been tested mostly as WSGI and as CGI script 
with Apache 2.2 (It should work with any web server supporting either
of these: WSGI, FCGI, FastCGI, SCGI, CGI)

1.1 Example: A single wiki as CGI with Apache2
----------------------------------------------

 1) Create and populate /var/www/mywiki
    # mkdir /var/www/mywiki
    # mkdir /var/lib/mywiki
    # cp -r /usr/share/moin/data /usr/share/moin/underlay /var/lib/mywiki

 2) Pass on the wiki to Apache:
    # chown -R www-data: /var/www/mywiki /var/lib/mywiki

 3) Configure Apache2:
    Add the following as /etc/apache2/sites-available/mywiki:

	<VirtualHost *:80>
		ServerName wiki.example.org
		DocumentRoot /var/www/mywiki/
 		Alias __STATICPATH__/applets/FCKeditor/ "/usr/share/fckeditor/"
		Alias __STATICPATH__/ "/usr/share/moin/htdocs/"
		ScriptAlias /MyWiki "/usr/share/moin/server/moin.cgi"
	</VirtualHost>

 4) Configure MoinMoin:
    Edit /etc/moin/mywiki.py to include these lines:

	sitename = u'MyWiki' # [Unicode]
	data_dir = '/var/lib/mywiki/data'
	data_underlay_dir = '/var/lib/mywiki/underlay'
	superuser = [u"YourName", ]

    Edit /etc/moin/wikilist to include this line:

	www-data wiki.example.org/

 5) Activate wiki:
    # a2ensite mywiki
    # invoke-rc.d apache2 reload

 6) Visit your new wiki at http://your.site/MyWiki/LanguageSetup
    then create you account (name according to the superuser you specified
    above).

 7) Install the language pack you want to use (typically, you want to install
    the "all_pages" pack in English, plus the languages use in your wiki).


For more complex setups for apache 1.3 and 2.0, you may find inspiration
in *.conf files below /usr/share/doc/python-moinmoin/examples/*.conf .

For more info, both related to above example and other setups like
standalone, read the upstream file
/usr/share/doc/python-moinmoin/INSTALL.html .


2. Upgrading from earlier versions of moin
------------------------------------------

Upgrading typically involve the following steps:

 *. Make a backup!
 1. Add your wiki to /etc/moin/wikilist
 2. Upgrade python-moinmoin package.
 3. Migrate/convert the content of the data folder (see note below)
 4. Update the underlay, moin.{wsgi,cgi,fcgi,..} and interwiki.txt
 5. Clean the cache.
 6. Fix the webserver configuration files.
 *. Test!

Those steps are documented in /usr/share/doc/python-moinmoin/NEWS.Debian(.gz)
and in upstream's documentations:

 - /usr/share/doc/python-moinmoin/README.migration(.gz)
 - /usr/share/doc/python-moinmoin/changelog(.gz) (= upstream's CHANGE file)
 - /usr/share/doc/python-moinmoin/UPDATE.html
   (or http://moinmo.in/HelpOnUpdating )

*The* most common cause of problems after an upgrade is that people
don't clean the cache. Remember to do this after you've made a major
change such as a new moin Moin upstream release or a new python
version. A typical invocation of Moin on a standard Debian system here
is going to be (as root):

# moin --config-dir=/etc/moin maint cleancache

Note:
  Debian packaging includes a helper script for "moin migrate", named 
  moin-mass-migrate, to automatically apply the "migration scripts" on
  package updates (or whenever you invoke the script yourself). Add your
  MoinMoin wikis to /etc/moin/wikilist to enable the automation.


3. "Moin ... <command>"
-----------------------

There are a lot of useful extra commands provided by Moin: account
administration, data migration, etc. Read the docs for more
information about what's available here. As a Moin admin they will
make your life much easier!


4. Always use farmconfig
------------------------

The Debian packaging of MoinMoin has farmconfig enabled by default, and
it is recommended to always use farmconfig instead of wikiconfig.py.

Some upgrades of MoinMoin require migration of data (as was the case
from 1.2.4 to 1.3.4). Future Debian packaging routines may offer to do
the migration automatically, but only for farmconfig wikis!


5. Additional notes
-------------------

If you want to customize the visual layout of the wiki, copy the htdoc
directory as well, change the Alias line, and (optionally) change the
url_prefix option in moin_config.py.

The dictionary can be improved by adding (symlinks to) wordlists to the
data/dict. If one of the wordlist packages (eg. wenglish, wdutch, 
miscfiles) is installed you can link to /usr/share/dict/words or the
file(s) directly. Alternatively (or in addition) you can put other
wordlists into the moin dict folder. One place to look for wordlists is
here: http://wetelephant.cotse.com/wordlists/

Beware if copying /usr/share/moin to a different location: The symlink
/usr/share/moin/data/dict/word may need to be adjusted to properly point
to /usr/share/dict/words - or replaced as described above.

Read more about the options on the wiki page HelpOnConfiguration.


6. Optional Features
--------------------

Some optional features requires extra packages and configuration

GUI editor
    In order to use GUI editor, you need to install the package
    fckeditor, and make sure you have two lines likes thoses ones
    in apache configuration file:
        Alias __STATICPATH__/applets/FCKeditor/ "/usr/share/fckeditor/"
        Alias __STATICPATH__/ "/usr/share/moin/htdocs/"

    In order to disable GUI editor, you might want to add those two lines
    in the wiki configuration (typically /etc/moin/mywiki.py)
        editor_force = True
        editor_default = 'text'

DocBook rendering.
    In order to render wiki pages as DocBook (i.e. xml), you will need 
    to install the package python-xml. (When missing, moinmoin will 
    display the error "No module named ext.reader")

XSLT Rendering
    In order to use XSLT Rendering (i.e. xml+xslt), you will need to 
    install the packages python-4suite-xml, docbook-xsl and xalan.
    You will also need to enable "allow_xslt = 1" in you configuration
    file. (Thoses are required to render "#format docbook" pages)

ReStructuredText rendering
    In order to use reStructuredText rendering (rst), you need to 
    install the package python-docutils.

Full text indexing / Xapian
    In order for full-text indexing to work, you will need to install
    the packages python-xapian. Moin will also use antiword and xls2csv
    (from the catdoc package) to index the contents of word and excel.
    xpdf-utils will provide PDF indexing.

Chart for Moinmoin statistics
    Moinmoin used to be able to create some graphical chart, using
    python-gdchart v1 libraries.
    This feature isn't supported by this package, since the package
    python-gdchart isn't in Debian anymore. (see bug #374126).

more on /usr/share/doc/python-moinmoin/REQUIREMENTS(.gz)

