Changes between Version 2 and Version 3 of TracModPython


Ignore:
Timestamp:
09/27/05 22:35:02 (21 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracModPython

    v2 v3  
    11= Trac and mod_python =
    22
    3 Trac 0.7.1 and later supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably and permits use of many Apache features not possible with tracd/mod_proxy.
     3Trac supports [http://www.modpython.org/ mod_python], which speeds up Trac's response times considerably and permits use of many Apache features not possible with [wiki:TracStandalone tracd]/mod_proxy.
    44
    5 Be sure to grab mod_python 3.1.3 and later for ''SetHandler'' ''mod_python'' directive to work.  Also, older versions may generate an internal error.  [http://projects.edgewall.com/trac/ticket/1090 #1090]
    6 
    7 == Trac Trunk Configuration ==
    8 
    9 The examples below are written for Trac 0.8.x.  If you are running Trac from the trunk source you will need to make a modification to the configuration.
    10 
    11 The mod_python handler class is changed in trunk revision [1287] and later, so you'll need to substitute the following line:
    12 
    13 {{{
    14    PythonHandler trac.ModPythonHandler
    15 }}}
    16 
    17 with this one:
    18 
    19 {{{
    20    PythonHandler trac.web.modpython_frontend
    21 }}}
     5Be sure to grab mod_python 3.1.3 and later for ''SetHandler'' ''mod_python'' directive to work.  Also, older versions may generate an internal error (see [http://projects.edgewall.com/trac/ticket/1090 #1090])
    226
    237== Simple configuration ==
    248
    25 Here's a typical Trac CGI/Apache setup:
    26 
     9If you just installed mod_python, you may have to add a line to load the module in the Apache configuration:
    2710{{{
    28 ScriptAlias /projects/myproject /path/to/python/share/trac/cgi-bin/trac.cgi
    29 <Location /projects/myproject>
    30    SetEnv TRAC_ENV /var/trac/myproject
    31 </Location>
     11LoadModule python_module modules/mod_python.so
    3212}}}
    3313
    34 The equivalent mod_python setup is:
    35 
     14A simple setup of Trac on mod_python looks like this:
    3615{{{
    3716<Location /projects/myproject>
    3817   SetHandler mod_python
    3918   PythonHandler trac.ModPythonHandler
    40    PythonOption TracUriRoot "/projects/myproject"
    4119   PythonOption TracEnv /var/trac/myproject
     20   PythonOption TracUriRoot /projects/myproject
    4221</Location>
    4322}}}
    4423
    45 Note that the option ''TracUriRoot'' may or may not be necessary in your setup. Try without first, and if the URLs produced by Trac look wrong or if Trac does not seem to recognize the URLs correctly, add the ''TracUriRoot'' option.
     24Note that the option `TracUriRoot` may or may not be necessary in your setup. Try without first, and if the URLs produced by Trac look wrong or if Trac does not seem to recognize the URLs correctly, add the `TracUriRoot` option.
    4625
    47 Authentication works the same as for CGI:
    48 
     26Configuring authentication works the same as for [wiki:TracCgi#AddingAuthentication CGI]:
    4927{{{
    5028<Location "/projects/myproject/login">
    … …  
    5634}}}
    5735
    58 If your trac installation isn't installed in your Python path, you'll have to tell Apache where to find the {{{trac.ModPythonHandler}}} module by adding this line to the {{{<Location>}}} section:
    59 
     36If the Trac installation isn't installed in your Python path, you'll have to tell Apache where to find the Trac mod_python handler  using the `PythonPath` directive:
    6037{{{
    61 <Location "/projects/myproject">
    62   PythonPath "sys.path+['/path/to/trac']"
     38<Location /projects/myproject>
     39  ...
     40  PythonPath "sys.path + ['/path/to/trac']"
    6341  ...
    6442</Location>
    6543}}}
    6644
    67 == Setting up a project on the root of the webserver ==
    68 
    69 To install Trac on the root of the webserver (in a virtual host context for example) and make it available at the ''!http://some-hostname/'' URL, use the following:
    70 
    71 {{{
    72 <VirtualHost trac.example.org>
    73   ServerName trac.example.org
    74   Alias /trac /var/www/trac.example.org/htdocs/trac
    75   <Location />
    76     SetHandler mod_python
    77     PythonHandler trac.ModPythonHandler
    78 
    79 
    80     PythonOption TracUriRoot "/"
    81     PythonOption TracEnv /var/trac/myproject
    82   </Location>
    83   <Location /login>
    84     AuthType Basic
    85     AuthName "My Project"
    86     AuthUserFile /var/trac/myproject/.htaccess
    87     Require valid-user
    88   </Location>
    89   <Location /trac>
    90     SetHandler None
    91   </Location>
    92 </VirtualHost>
    93 }}}
    94 
    95 
    96 The path in the last {{{<Location>}}} block should match your {{{htdocs_location}}}. The directive "{{{SetHandler None}}}" allows us to escape mod_python and have Apache serve the static files (located at {{{/var/www/trac.example.org/htdocs/trac/}}} on the filesystem in this example). Any other URLs will be handled by mod_python.
    97 
    9845== Setting up multiple projects ==
    9946
    100 The Trac mod_python handler handler supports a configuration option similar to Subversion's {{{SvnParentPath}}}, called {{{TracEnvParentDir}}}:
    101 
     47The Trac mod_python handler handler supports a configuration option similar to Subversion's `SvnParentPath`, called `TracEnvParentDir`:
    10248{{{
    10349<Location /projects>
    10450  SetHandler mod_python
    10551  PythonHandler trac.ModPythonHandler
     52  PythonOption TracEnvParentDir /var/trac
    10653  PythonOption TracUriRoot /projects
    107   PythonOption TracEnvParentDir "/var/trac"
    10854</Location>
    10955}}}
    11056
    111 When you request the {{{/projects}}} URL, you will get a (currently very simple) listing of all subdirectories of the directory you set as {{{TracEnvParentDir}}}. Selecting any project in the list will bring you to the corresponding Trac instance. You should make sure that the configured directory only contains Trac environment directories that match the currently installed Trac version, because that is not checked prior to the generation of the project list.
     57When you request the `/projects` URL, you will get a listing of all subdirectories of the directory you set as `TracEnvParentDir`. Selecting any project in the list will bring you to the corresponding Trac environment.
    11258
    11359If you don't want to have the subdirectory listing as your projects home page you can use a
    114 
    11560{{{
    11661<LocationMatch "/.+/">
    11762}}}
    11863
    119 This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in yuor !DocumentRoot folder.
     64This will instruct Apache to use mod_python for all locations different from root while having the possibility of placing a custom home page for root in your !DocumentRoot folder.
    12065
    121 
    122 === Use different locations for htdocs and mod_python ===
    123 The mod_python location must be different than the trac htdocs location. For example, if you map Trac's htdocs location to {{{/trac}}} and then map your mod_python handler to {{{/trac}}} as well, you will encounter strange problems.  Configuration for the location of the htdocs is in the environment's ini file.
    124 
    125 == Setting up multiple projects as the root URL ==
    126 
    127 Let's say you want something like http://projects.yourdomain.com which has a list of all of the projects hosted on it.  However, you don't want to do manual configuration every time a new project is added.  Or, you'd like to minimize it.  Here's a quick sample:
    128 
    129 {{{
    130 Alias /trac/ /usr/share/trac/htdocs/
    131 <Directory "/usr/share/trac/htdocs">
    132    Order allow,deny
    133    Allow from all
    134 </Directory>
    135 
    136 <Location />
    137    SetHandler mod_python
    138    PythonHandler trac.ModPythonHandler
    139    PythonOption TracEnvParentDir "/var/trac"
    140    PythonOption TracUriRoot /
    141 </Location>
    142 
    143 <Location /project1/login>
    144    AuthType Basic
    145    AuthName "Project1"
    146    AuthUserFile /var/www/projects.yourdomain.com/security/users
    147    AuthGroupFile /var/www/projects.yourdomain.com/security/groups
    148    Require group project1-users
    149 </Location>
    150 
    151 <Location /project2/login>
    152    AuthType Basic
    153    AuthName "Project2"
    154    AuthUserFile /var/www/projects.yourdomain.com/security/users
    155    AuthGroupFile /var/www/projects.yourdomain.com/security/groups
    156    Require group project2-users
    157 </Location>
    158 
    159 <Location /trac>
    160    SetHandler none
    161 </Location>
    162 }}}
    163 
    164 A few things to note about this example:  all of the users are stored in one file, {{{/var/www/projects.yourdomain.com/security/users}}}.  Groups for these users are defined in the groups file, {{{/var/www/projects.yourdomain.com/security/groups}}}.  The Trac projects are all stored under {{{/var/trac}}}.
    165 
    166 To add a new project, you'll have to create a new user in the user file.  Then, create a new group for the project in the group file.  Finally, create a new <Location> block with a new {{{Require group}}} directive.  That's about it.
    167 
    168 You can also use the same authentication realm for all of the projects using a {{{<LocationMatch>}}} directive:
    169 
     66You can also use the same authentication realm for all of the projects using a `<LocationMatch>` directive:
    17067{{{
    17168<LocationMatch "/[^/]+/login">
    172    ...
     69  AuthType Basic
     70  AuthName "Trac"
     71  AuthUserFile /var/trac/.htaccess
     72  Require valid-user
    17373</LocationMatch>
    17474}}}
    17575
    17676== Troubleshooting ==
    177 
    178 === Setting up plugin cache directory ===
    179 
    180 {{{
    181 SetEnv PYTHON_EGG_CACHE /path/to/dir
    182 }}}
    18377
    18478=== Form submission problems ===
    … …  
    18882=== Using .htaccess ===
    18983
    190 Although it may seem trivial to rewrite the above configuration as a directory in your document root with a {{{.htaccess}}} file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.
     84Although it may seem trivial to rewrite the above configuration as a directory in your document root with a `.htaccess` file, this does not work. Apache will append a "/" to any Trac URLs, which interferes with its correct operation.
    19185
    19286It may be possible to work around this with mod_rewrite, but I failed to get this working. In all, it is more hassle than it is worth. Stick to the provided instructions. :)
    193 
    194 === mod_python does caching: beware ===
    195 
    196 When using mod_python you have to reload apache before changes to a trac.ini of a project or a projects templates take effect!
    197 
    198  ''Note: This doesn't apply to the current development version (0.9pre), where the configuration is reloaded automatically if it has changed.''
    19987
    20088=== Win32 Issues ===
    … …  
    20795=== OS X issues ===
    20896
    209 There is a mod_python issue on OSX: Look at the end of its README.
    210 You need to either define the environment variable DYLD_FORCE_FLAT_NAMESPACE before starting httpd
    211 or apply [http://www.dscpl.com.au/projects/vampire/PATCHES this patch] to mod_python.
     97When using mod_python on OS X you will not be able to restart Apache using `apachectl restart`. This is apparently fixed in mod_python 3.2, but there's also a patch available for earlier versions [http://www.dscpl.com.au/projects/vampire/patches.html here].
    21298
    213 Also note that there is an error in the module when you build it from source.  Basically an unpatched version will not respond correctly to the 'apachectl restart' command.  If you issue this command on an unpatched module your client will receive a 500 error from apache.  The patch needed to fix this problem is included below:
    214 
    215 {{{
    216 --- src/mod_python.c    Mon Feb 16 20:47:27 2004
    217 +++ /Usersjkp/mod_python.c      Wed Mar 16 21:15:49 2005
    218 @@ -31,6 +31,10 @@
    219   * (In a Python dictionary) */
    220  static PyObject * interpreters = NULL;
    221  
    222 +#ifdef WITH_THREAD
    223 +static apr_thread_mutex_t* interpreters_lock = 0;
    224 +#endif
    225 +
    226  apr_pool_t *child_init_pool = NULL;
    227  
    228  /**
    229 @@ -124,6 +128,8 @@
    230          name = MAIN_INTERPRETER;
    231  
    232  #ifdef WITH_THREAD
    233 +    apr_thread_mutex_lock(interpreters_lock);
    234 +
    235      PyEval_AcquireLock();
    236  #endif
    237  
    238 @@ -149,6 +155,8 @@
    239  
    240  #ifdef WITH_THREAD
    241      PyEval_ReleaseLock();
    242 +
    243 +    apr_thread_mutex_unlock(interpreters_lock);
    244  #endif
    245  
    246      if (! idata) {
    247 @@ -469,6 +477,9 @@
    248      const char *userdata_key = "python_init";
    249      apr_status_t rc;
    250  
    251 +    /* fudge for Mac OS X with Apache where Py_IsInitialized() broke */
    252 +    static int initialized = 0;
    253 +
    254      apr_pool_userdata_get(&data, userdata_key, s->process->pool);
    255      if (!data) {
    256          apr_pool_userdata_set((const void *)1, userdata_key,
    257 @@ -490,13 +501,16 @@
    258      }
    259  
    260      /* initialize global Python interpreter if necessary */
    261 -    if (! Py_IsInitialized())
    262 +    if (initialized == 0 || ! Py_IsInitialized())
    263      {
    264 +        initialized = 1;
    265  
    266          /* initialze the interpreter */
    267          Py_Initialize();
    268  
    269  #ifdef WITH_THREAD
    270 +        apr_thread_mutex_create(&interpreters_lock,APR_THREAD_MUTEX_UNNESTED,p);
    271 +
    272          /* create and acquire the interpreter lock */
    273          PyEval_InitThreads();
    274  #endif
    275 }}}
    276 
    277 
    278 ''Mar. 25/05''
    279 
    280 The patch listed above causes complaints when attempting to apply it; also, the URL for the OS X patch is broken. I found that patch as well as an additional one for mod_python for use with a multithreaded MPM [http://www.dscpl.com.au/projects/vampire/patches.html here] (same site; pages have been shuffled around).
    28199----
    282 See also TracGuide, TracInstall, TracMultipleProjects
     100See also TracGuide, TracInstall, TracCgi, TracFastCgi