Premiere version : mise en route du suivi.
[auf_roundup.git] / 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