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 You should proxy through apache and use its SSL service. See the previous
 100 question on how to proxy through apache.
 101
 102
 103 Roundup runs very slowly on my XP machine when accessed from the Internet
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106 The issue is probably related to host name resolution for the client
 107 performing the request. You can turn off the resolution of the names
 108 when it's so slow like this. To do so, edit the module
 109 roundup/scripts/roundup_server.py around line 77 to add the following
 110 to the RoundupRequestHandler class:
 111
 112      def address_string(self):
 113          return self.client_address[0]
 114
 115
 116 Templates
 117 ---------
 118
 119 What is that stuff in the tracker html directory?
 120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 121
 122 This is the template code that Roundup uses to display the various pages.
 123 This is based upon the template markup language in Zope called, oddly
 124 enough "Zope Page Templates". There's documentation in the Roundup
 125 customisation_ documentation. For more information have a look at:
 126
 127    http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/
 128
 129 specifically chapter 10 "Using Zope Page Templates" and chapter 14 "Advanced
 130 Page Templates".
 131
 132
 133 But I just want a select/option list for ....
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 Really easy... edit ``html/issue.item``. For 'nosy', change line 53 from::
 137
 138   <span tal:replace="structure context/nosy/field" />
 139
 140 to::
 141
 142   <span tal:replace="structure context/nosy/menu" />
 143
 144 For 'assigned to', change line 61 from::
 145
 146   <td tal:content="structure context/assignedto/field">assignedto menu</td>
 147
 148 to::
 149
 150   <td tal:content="structure context/assignedto/menu">assignedto menu</td>
 151
 152
 153
 154 Great! But now the select/option list is too big
 155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 156
 157 Thats a little harder (but only a little ;^)
 158
 159 Again, edit ``html/issue.item``. For nosy, change line 53 from:
 160
 161   <span tal:replace="structure context/nosy/field" />
 162
 163 to::
 164
 165   <span tal:replace="structure python:context.nosy.menu(height=3)" />
 166
 167 for more information, go and read about Zope Page Templates.
 168
 169
 170 Using Roundup
 171 -------------
 172
 173 I got an error and I cant reload it!
 174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 175
 176 If you're using Netscape/Mozilla, try holding shift and pressing reload.
 177 If you're using IE then install Mozilla and try again ;^)
 178
 179
 180 I keep getting logged out
 181 ~~~~~~~~~~~~~~~~~~~~~~~~~
 182
 183 Make sure that the ``tracker`` -> ``web`` setting in your tracker's
 184 config.ini is set to the URL of the tracker.
 185
 186
 187 How is sorting performed, and why does it seem to fail sometimes?
 188 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 189
 190 When we sort items in the hyperdb, we use one of a number of methods,
 191 depending on the properties being sorted on:
 192
 193 1. If it's a String, Number, Date or Interval property, we just sort the
 194    scalar value of the property. Strings are sorted case-sensitively.
 195 2. If it's a Link property, we sort by either the linked item's "order"
 196    property (if it has one) or the linked item's "id".
 197 3. Mulitlinks sort similar to #2, but we start with the first
 198    Multilink list item, and if they're the same, we sort by the second item,
 199    and so on.
 200
 201 Note that if an "order" property is defined on a Class that is used for
 202 sorting, all items of that Class *must* have a value against the "order"
 203 property, or sorting will result in random ordering.
 204
 205 .. _`customisation`: customizing.html
 206