/shabti/templates/moinmoin/data/moin/underlay/pages/HelpOnInstalling(2f)ApacheWithModPython/revisions/00000001

  1## Please edit system and help pages ONLY in the master wiki!
  2## For more information, please see MoinMoin:MoinDev/Translation.
  3##master-page:Unknown-Page
  4##master-date:Unknown-Date
  5#acl -All:write Default
  6#format wiki
  7#language en
  8
  9<<TableOfContents>>
 10
 11= Why Use mod_python =
 12
 13[[http://modpython.org/|mod_python]] embeds the python interpreter into
 14the apache server. This saves initialization time and the need of
 15forking cgi scripts. It doesn't have the ability to run as different
 16users. It will always run as the main apache user and group. Be sure
 17that your wiki data files are accessible and writable by your apache
 18server.
 19
 20<!> The basic configuration is suitable for mod_python 3.1.3 and later. If you use older version, see the section "Older mod_python versions"
 21
 22<!> mod_python will cause your apache processes to increase their
 23memory requirements considerably - especially as apache runs many
 24separate processes which will each need to have their own copy of the
 25python code and data in the process memory space.  You may find that
 26FastCGI, as detailed in HelpOnInstalling/FastCgi is rather
 27more efficient in this respect.
 28
 29= Basic configuring =
 30
 31 1. Install mod_python
 32 1. Set up a wiki instance
 33 1. Edit `wikiconfig.py`
 34 3. Changes to Apache `httpd.conf`
 35 1. Restart Apache
 36
 37The sample configurations below are for a wiki instance called `mywiki` installed in a directory `/var/www/moin/mywiki` with the main MoinMoin installation installed in python's default site library path. The wiki appears as URL `/mywiki` under the server - ie `http://my.ser.ver/mywiki`.  You will need to change these to reflect your installation.
 38
 39== Install mod_python ==
 40
 41Most people will just add a `mod_python` package to their current operating system installation.  If you are building from source then you should consult the [[http://modpython.org/live/current/doc-html/|mod_python documentation]].
 42
 43The mod_python installation should have added some lines to the Apache configuration file - either in the file itself or in an included configuration file (for example on Red Hat or Fedora linux the mod_python configuration is in `/etc/httpd/conf.d/python.conf`).
 44
 45Make sure you have this line in `httpd.conf` or mod_python will not work:
 46{{{
 47LoadModule python_module modules/mod_python.so
 48}}}
 49
 50After this restart Apache and make sure that it starts successfully, and that the error log has a line similar to this:-
 51{{{
 52[Sat Jan 01 15:40:49 2005] [notice] mod_python: Creating 4 session mutexes based on 150 max processes and 0 max threads.
 53}}}
 54
 55You may need to change some environment variables on (eg) FreeBSD - this is detailed in the port installation message.
 56
 57== Set up a wiki instance ==
 58
 59This is done as shown in [[HelpOnInstalling/WikiInstanceCreation|WikiInstanceCreation]]. Its recommended to first configure the wiki with cgi and check that it works, then change the configuratin to use mod_python. This allows you be sure that any problems are in the mod_python transition rather than the basic MoinMoin installation.
 60
 61 1. Copy moin.cgi into your wiki directory
 62 1. Configure `httpd.conf` as cgi first (the shown Alias is for moin version 1.6.0):
 63  {{{
 64Alias /moin_static160/ "/usr/share/moin/htdocs/"
 65ScriptAlias /mywiki "/var/www/moin/mywiki/moin.cgi"
 66}}}
 67
 68Restart Apache and make test that your wiki works.
 69
 70== Edit `wikiconfig.py` ==
 71
 72Make sure you use only absolute paths - relative paths will not work!
 73{{{
 74data_dir = '/var/www/moin/mywiki/data/'
 75data_underlay_dir = '/var/www/moin/mywiki/underlay/'
 76}}}
 77
 78If you do not want to use absolute paths, you can use Python's os module to construct the relative paths:
 79{{{import os
 80data_dir = os.path.join(os.path.dirname(__file__), 'data/')
 81data_underlay_dir = os.path.join(os.path.dirname(__file__), 'underlay/')
 82}}}
 83
 84Test that the wiki works after this change.
 85
 86
 87== Changes to Apache `httpd.conf` ==
 88
 89After your wiki is running as cgi script, convert it to run with mod_python. 
 90
 91If you run your wiki as cgi as we recommended before, remove or comment the ScriptAlias directive:
 92{{{
 93#ScriptAlias /mywiki "/var/www/moin/mywiki/moin.cgi"
 94}}}
 95
 96Add a `Location` directive:
 97{{{
 98<Location /mywiki>
 99    SetHandler python-program
100    # Add the path of your wiki directory
101    PythonPath "['/var/www/moin/mywiki'] + sys.path"
102    PythonHandler MoinMoin.request.request_modpython::Request.run
103</Location>
104}}}
105
106If you have multiple MoinMoin instances then add one location directive for each one (changing the paths as appropriate) and add a line with the directive `PythonInterpreter mywiki` to each Location section. With this directive different subinterpreters with completely separate namespaces will be used for each wiki (see [[http://modpython.org/live/current/doc-html/pyapi-interps.html|here]] for details).
107
108If you did not install MoinMoin in the default location, you will have to add the path to MoinMoin to the system path:
109{{{
110    PythonPath "['/var/www/moin/mywiki', '/prefix/lib/python2.x/site-packages'] + sys.path"
111}}}
112
113Restart Apache - everything should now work correctly.
114
115= Solving problems for non-root-mounted wikis =
116
117 /!\ If your wiki does not have a root URL (like `http://www.example.com/FrontPage`), then you might need to follow the next steps:
118
119On some installations, mod_python hands MoinMoin incorrect script_name and path_info. It usually happens when using the Apache Location directive, with a wiki in an arbitary path:
120{{{
121<Location /farm/mywiki>
122    ...
123</Location>
124}}}
125This will not work, because its not clear what is the script name, since with location setup, there is no real script.
126
127To solve this problem, use a `PythonOption` directive:
128{{{
129<Location /farm/mywiki>
130    # Location value must match the Apache Location value!
131    PythonOption Location /farm/mywiki
132    ...
133</Location>
134}}}
135
136
137= Configuring root wiki =
138
139You may wish to have your wiki appearing at the root of your webserver - for example so that `http://wiki.example.com/` will map to your wiki rather than having to use `http://wiki.example.com/mywiki/`.  This requires a slightly different form of configuration using `mod_rewrite` - this is a standard module of recent Apache distributions, and is often enabled by default.
140
141You need to set up your wiki instance as described above, and also copy `moinmodpy.py` from the Moin installation directory to the wiki instance directory (`/var/www/moin/mywiki` in these examples).
142
143The Apache configuration needs `mod_rewrite` enabled - so the line
144{{{
145LoadModule rewrite_module modules/mod_rewrite.so
146}}}
147should appear in the first part of the `httpd.conf` configuration file.
148
149The wiki and virtual host configuration should look like this (Alias is for moin version 1.6.0):-
150{{{
151<VirtualHost *:80>
152  ServerAdmin postmaster@example.com
153  DocumentRoot /var/www/html
154  ServerName wiki.example.com
155  Alias /moin_static160/ "/usr/share/moin/htdocs/"
156
157  # Rewrite urls
158  RewriteEngine On
159  RewriteLogLevel 0
160  # map /wiki static files to Moin htdocs
161  RewriteRule ^/moin_static160/(.*)$ /usr/share/moin/htdocs/$1 [last]
162  RewriteRule ^/robots.txt$ /usr/share/moin/htdocs/robots.txt [last]
163  RewriteRule ^/favicon.ico$ /usr/share/moin/htdocs/favicon.ico [last]
164  # map everything else to server script
165  RewriteRule ^(.*)$ /var/www/moin/mywiki/moinmodpy.py$1
166
167  <Directory "/var/www/moin/testwiki">
168    # Modpy stuff
169    AddHandler python-program .py
170    # Add the path to the wiki directory, where
171    # moinmodpy.py and wikiconfig.py are located.
172    PythonPath "['/var/www/moin/mywiki'] + sys.path"
173    PythonHandler MoinMoin.request.request_modpython::Request.run
174  </Directory>
175</VirtualHost>
176}}}
177
178Apache should be restarted, and the !FrontPage of `mywiki` should now appear at `http://wiki.example.com/`.
179
180Other ways of handling root level wikis with Apache are detailed in the appropriately named HelpOnConfiguration/ApacheVoodoo.
181
182= Older mod_python versions =
183
184mod_python versions 2.7.10, 3.0.4 and 3.1.2b have a bug in `apache.resolve_object`. This bug was reported to the mod_python
185maintainers and has been fixed in the 3.1.3 release. The best fix for this is to update to the current release. However if you are unable to do this there are 2 possible solutions:
186
187== Use a wrapper script ==
188
189MoinMoin come with a `moinmodpy.py` wrapper script, and this could be used by changing the `PythonPath` and `PythonHandler` directives as shown in the `moinmodpy.htaccess` file. 
190
191== Fix mod_python ==
192mod_python has a small resolver bug in versions 2.7.10, 3.0.4 and 3.1.2b.
193The method `resolve_object` in `mod_python/apache.py` checks the wrong
194object, and so the lookup for `RequestModPy.run` fails.
195
196To fix it you need to change the method `resolve_object` (around line 551 for
197mod_python 3.1.2b) from
198
199{{{
200        if silent and not hasattr(module, obj_str):
201            return None
202}}}
203
204to
205
206{{{
207        if silent and not hasattr(obj, obj_str):
208            return None
209}}}
210
211
212= Troubleshooting =
213
214Page access gives apache error::
215 {{{PythonHandler MoinMoin.request::RequestModPy.run: OSError: [Errno 2] No such file or directory: 'data/user'}}}
216 This appears to be caused by you not having an absolute path for `data_dir` in `moin_config.py`.  There are several other lines of error traceback preceding this one in the apache error log.  Fix the path in `moin_config.py`.