doc/FAQ.txt

   1 ===========
   2 Roundup FAQ
   3 ===========
   4
   5 .. contents::
   6
   7
   8 Installation
   9 ------------
  10
  11 Living without a mailserver
  12 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  13
  14 Remove the nosy reactor - delete the tracker file
  15 ``detectors/nosyreactor.py`` from your tracker home.
  16
  17
  18 The cgi-bin is very slow!
  19 ~~~~~~~~~~~~~~~~~~~~~~~~~
  20
  21 Yep, it sure is. It has to start up Python and load all of the support
  22 libraries for *every* request.
  23
  24 The solution is to use the built in server (or possibly the mod_python
  25 or WSGI support).
  26
  27 To make Roundup more seamless with your website, you may place the built
  28 in server behind apache and link it into your web tree (see below).
  29
  30
  31 How do I put Roundup behind Apache
  32 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33
  34 We have a project (foo) running on ``tracker.example:8080``.
  35 We want ``http://tracker.example/issues`` to use the roundup server, so we
  36 set that up on port 8080 on ``tracker.example`` with the ``config.ini`` line::
  37
  38   [tracker]
  39   ...
  40   web = 'http://tracker.example/issues/'
  41
  42 We have a "foo_issues" tracker and we run the server with::
  43
  44   roundup-server -p 8080 issues=/home/roundup/trackers/issues
  45
  46 Then, on the Apache machine (eg. redhat 7.3 with apache 1.3), in
  47 ``/etc/httpd/conf/httpd.conf`` uncomment::
  48
  49   LoadModule proxy_module       modules/libproxy.so
  50
  51 and::
  52
  53   AddModule mod_proxy.c
  54
  55 Then add::
  56
  57   # roundup stuff (added manually)
  58   <IfModule mod_proxy.c>
  59   # proxy through one tracker
  60   ProxyPass /issues/ http://tracker.example:8080/issues/
  61   # proxy through all tracker(*)
  62   #ProxyPass /roundup/ http://tracker.example:8080/
  63   </IfModule>
  64
  65 Then restart Apache. Now Apache will proxy the request on to the
  66 roundup-server.
  67
  68 Note that if you're proxying multiple trackers, you'll need to use the
  69 second ProxyPass rule described above. It will mean that your TRACKER_WEB
  70 will change to::
  71
  72   TRACKER_WEB = 'http://tracker.example/roundup/issues/'
  73
  74 Once you're done, you can firewall off port 8080 from the rest of the world.
  75
  76 Note that in some situations (eg. virtual hosting) you might need to use a
  77 more complex rewrite rule instead of the simpler ProxyPass above. The
  78 following should be useful as a starting template::
  79
  80   # roundup stuff (added manually)
  81   <IfModule mod_proxy.c>
  82
  83   RewriteEngine on
  84
  85   # General Roundup
  86   RewriteRule ^/roundup$  roundup/    [R]
  87   RewriteRule ^/roundup/(.*)$ http://tracker.example:8080/$1   [P,L]
  88
  89   # Handle Foo Issues
  90   RewriteRule ^/issues$  issues/    [R]
  91   RewriteRule ^/issues/(.*)$ http://tracker.example:8080/issues/$1 [P,L]
  92
  93   </IfModule>
  94
  95
  96 How do I run Roundup through SSL (HTTPS)?
  97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98
  99 The preferred way of using SSL is to proxy through apache and use its
 100 SSL service. See the previous question on how to proxy through apache.
 101
 102 The standalone roundup-server now also has SSL support which is still
 103 considered experimental. For details refer to the documentation of
 104 roundup server, in particular to the generated configuration file
 105 generated with ::
 106
 107     roundup-server --save-config
 108
 109 that describes the needed option in detail. With the standalone server
 110 now XMLRPC over SSL works, too.
 111
 112
 113 Roundup runs very slowly on my XP machine when accessed from the Internet
 114 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 115
 116 The issue is probably related to host name resolution for the client
 117 performing the request. You can turn off the resolution of the names
 118 when it's so slow like this. To do so, edit the module
 119 roundup/scripts/roundup_server.py around line 77 to add the following
 120 to the RoundupRequestHandler class::
 121
 122      def address_string(self):
 123          return self.client_address[0]
 124
 125
 126 Templates
 127 ---------
 128
 129 What is that stuff in the tracker html directory?
 130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 131
 132 This is the template code that Roundup uses to display the various pages.
 133 This is based upon the template markup language in Zope called, oddly
 134 enough "Zope Page Templates". There's documentation in the Roundup
 135 customisation_ documentation. For more information have a look at:
 136
 137    http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/
 138
 139 specifically chapter 10 "Using Zope Page Templates" and chapter 14 "Advanced
 140 Page Templates".
 141
 142
 143 But I just want a select/option list for ....
 144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 145
 146 Really easy... edit ``html/issue.item.html``. For ``nosy``, change the line
 147 (around line 69) from::
 148
 149   <span tal:replace="structure context/nosy/field" />
 150
 151 to::
 152
 153   <span tal:replace="structure context/nosy/menu" />
 154
 155 For ``assigned to``, this is already done around line 77::
 156
 157   <td tal:content="structure context/assignedto/menu">assignedto menu</td>
 158
 159
 160
 161 Great! But now the select/option list is too big
 162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 163
 164 Thats a little harder (but only a little ;^)
 165
 166 Again, edit ``html/issue.item``. For nosy, change line (around line 69) from::
 167
 168   <span tal:replace="structure context/nosy/field" />
 169
 170 to::
 171
 172   <span tal:replace="structure python:context.nosy.menu(height=3)" />
 173
 174 for more information, go and read about Zope Page Templates.
 175
 176
 177 Using Roundup
 178 -------------
 179
 180 I got an error and I cant reload it!
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 If you're using Netscape/Mozilla, try holding shift and pressing reload.
 184 If you're using IE then install Mozilla and try again ;^)
 185
 186
 187 I keep getting logged out
 188 ~~~~~~~~~~~~~~~~~~~~~~~~~
 189
 190 Make sure that the ``tracker`` -> ``web`` setting in your tracker's
 191 config.ini is set to the URL of the tracker.
 192
 193 I'm getting infinite redirects in the browser
 194 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 195
 196 A wrong value for the ``tracker`` -> ``web`` setting may also result in
 197 infinite redirects, see http://issues.roundup-tracker.org/issue2537286
 198
 199
 200 How is sorting performed, and why does it seem to fail sometimes?
 201 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 202
 203 When we sort items in the hyperdb, we use one of a number of methods,
 204 depending on the properties being sorted on:
 205
 206 1. If it's a String, Number, Date or Interval property, we just sort the
 207    scalar value of the property. Strings are sorted case-sensitively.
 208 2. If it's a Link property, we sort by either the linked item's "order"
 209    property (if it has one) or the linked item's "id".
 210 3. Mulitlinks sort similar to #2, but we start with the first
 211    Multilink list item, and if they're the same, we sort by the second item,
 212    and so on.
 213
 214 Note that if an "order" property is defined on a Class that is used for
 215 sorting, all items of that Class *must* have a value against the "order"
 216 property, or sorting will result in random ordering.
 217
 218 .. _`customisation`: customizing.html
 219