X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2FFAQ.txt;h=8a8d9e2cc7cc8ad0cb3bcce820bd9abce01f7e38;hb=4dcc778d7c85e0d99bbc4fe0c64c5f463edc6703;hp=253d60e2e7eead355aa3cd30a2f712a1130a0266;hpb=f6c6a656c4b207ecaadbc40516ef44f56f9034fc;p=roundup.git
diff --git a/doc/FAQ.txt b/doc/FAQ.txt
index 253d60e..8a8d9e2 100644
--- a/doc/FAQ.txt
+++ b/doc/FAQ.txt
@@ -1,102 +1,219 @@
+===========
Roundup FAQ
+===========
- '$Date: 2002-02-14 08:50:14 $'
+.. contents::
- NOTE: This is just a grabbag, most of this should go into documentation.
-Changing HTML layout
+Installation
+------------
+
+Living without a mailserver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Remove the nosy reactor - delete the tracker file
+``detectors/nosyreactor.py`` from your tracker home.
+
+
+The cgi-bin is very slow!
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yep, it sure is. It has to start up Python and load all of the support
+libraries for *every* request.
+
+The solution is to use the built in server (or possibly the mod_python
+or WSGI support).
+
+To make Roundup more seamless with your website, you may place the built
+in server behind apache and link it into your web tree (see below).
+
+
+How do I put Roundup behind Apache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We have a project (foo) running on ``tracker.example:8080``.
+We want ``http://tracker.example/issues`` to use the roundup server, so we
+set that up on port 8080 on ``tracker.example`` with the ``config.ini`` line::
- Note changes to the files in html take place immediatly without
- restart, even when running roundup-server.
+ [tracker]
+ ...
+ web = 'http://tracker.example/issues/'
- Displaying whole messages not only the summary
+We have a "foo_issues" tracker and we run the server with::
- Modify instance/html/msg.index change::
+ roundup-server -p 8080 issues=/home/roundup/trackers/issues
-
|
+Then, on the Apache machine (eg. redhat 7.3 with apache 1.3), in
+``/etc/httpd/conf/httpd.conf`` uncomment::
- to::
+ LoadModule proxy_module modules/libproxy.so
-
|
+and::
- displays the whole message not only the first line and 'pre'
- prevents the browser from reformatting.
+ AddModule mod_proxy.c
- Getting the nosy list picker instead of textfield.
+Then add::
- In classic template there is plenty of space below the text field.
- So one could modify instance/html/issue.item to use it.
+ # roundup stuff (added manually)
+
+ # proxy through one tracker
+ ProxyPass /issues/ http://tracker.example:8080/issues/
+ # proxy through all tracker(*)
+ #ProxyPass /roundup/ http://tracker.example:8080/
+
- At the file top set 'border=1' to see cell boundaries, then
- replace::
+Then restart Apache. Now Apache will proxy the request on to the
+roundup-server.
- |
+Note that if you're proxying multiple trackers, you'll need to use the
+second ProxyPass rule described above. It will mean that your TRACKER_WEB
+will change to::
+
+ TRACKER_WEB = 'http://tracker.example/roundup/issues/'
+
+Once you're done, you can firewall off port 8080 from the rest of the world.
+
+Note that in some situations (eg. virtual hosting) you might need to use a
+more complex rewrite rule instead of the simpler ProxyPass above. The
+following should be useful as a starting template::
+
+ # roundup stuff (added manually)
+
+
+ RewriteEngine on
- by::
+ # General Roundup
+ RewriteRule ^/roundup$ roundup/ [R]
+ RewriteRule ^/roundup/(.*)$ http://tracker.example:8080/$1 [P,L]
+
+ # Handle Foo Issues
+ RewriteRule ^/issues$ issues/ [R]
+ RewriteRule ^/issues/(.*)$ http://tracker.example:8080/issues/$1 [P,L]
+
+
- |
- and remove the last cell in the next four rows, either by deleting a cell
- or by reducing colspan.
+How do I run Roundup through SSL (HTTPS)?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Want to see the issue id (the number) on the issue item display
+The preferred way of using SSL is to proxy through apache and use its
+SSL service. See the previous question on how to proxy through apache.
- The number is really a central information and not an internal one.
+The standalone roundup-server now also has SSL support which is still
+considered experimental. For details refer to the documentation of
+roundup server, in particular to the generated configuration file
+generated with ::
- In file INSTANCE/html/issue.item displays the creator, so one could add
- the number to it.::
+ roundup-server --save-config
-
- () |
+that describes the needed option in detail. With the standalone server
+now XMLRPC over SSL works, too.
- to see::
-
- (issue by ) |
+Roundup runs very slowly on my XP machine when accessed from the Internet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Installation
+The issue is probably related to host name resolution for the client
+performing the request. You can turn off the resolution of the names
+when it's so slow like this. To do so, edit the module
+roundup/scripts/roundup_server.py around line 77 to add the following
+to the RoundupRequestHandler class::
+
+ def address_string(self):
+ return self.client_address[0]
+
+
+Templates
+---------
+
+What is that stuff in the tracker html directory?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the template code that Roundup uses to display the various pages.
+This is based upon the template markup language in Zope called, oddly
+enough "Zope Page Templates". There's documentation in the Roundup
+customisation_ documentation. For more information have a look at:
+
+ http://docs.zope.org/zope2/zope2book/
+
+specifically chapter 10 "Using Zope Page Templates" and chapter 14 "Advanced
+Page Templates".
+
+
+But I just want a select/option list for ....
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Really easy... edit ``html/issue.item.html``. For ``nosy``, change the line
+(around line 69) from::
+
+
+
+to::
+
+
+
+For ``assigned to``, this is already done around line 77::
+
+ assignedto menu |
+
+
+
+Great! But now the select/option list is too big
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Thats a little harder (but only a little ;^)
+
+Again, edit ``html/issue.item``. For nosy, change line (around line 69) from::
+
+
+
+to::
+
+
- Living without a mailserver.
+for more information, go and read about Zope Page Templates.
- Remove the nosy reactor, means delete the file 'INSTANCE/detectors/nosyreactor.py'.
- Rights issues (MISSING)
+Using Roundup
+-------------
- Different jobs run under different users.
+I got an error and I cant reload it!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- * Standalone roundup-server is started by whome ?
+If you're using Netscape/Mozilla, try holding shift and pressing reload.
+If you're using IE then install Mozilla and try again ;^)
- * Running cgi under apache.
- * roundup-mailgw called via .forward from MTA, or running a cron job
- fetching via pop.
+I keep getting logged out
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Make sure that the ``tracker`` -> ``web`` setting in your tracker's
+config.ini is set to the URL of the tracker.
-Troubleshooting
+I'm getting infinite redirects in the browser
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- mailgw bouncing
+A wrong value for the ``tracker`` -> ``web`` setting may also result in
+infinite redirects, see http://issues.roundup-tracker.org/issue2537286
- messages are bouncing with the following error message.::
- Command died with status 1:
- "/usr/local/bin/python /usr/local/bin/roundup-mailgw /home/roundup".
- Command output: Traceback (most recent call last):
- File "/usr/local/bin/roundup-mailgw", line 178, in ? sys.exit(main(sys.argv))
- File "/usr/local/bin/roundup-mailgw", line 153, in main db =
- instance.open('admin') AttributeError: '_roundup_instance_1' module
- has no attribute 'open'
+How is sorting performed, and why does it seem to fail sometimes?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Happens when roundup-mailgw is called by a user that doesn't have
- read/execute permissions to the instance_home directory and sub
- directories.
+When we sort items in the hyperdb, we use one of a number of methods,
+depending on the properties being sorted on:
- An easy way to test whether it's a permissions problem, or some other mail
- server configuration problem is to cat an email-formatted text file
- directly to the roundup-mailgw script as the roundup user.::
+1. If it's a String, Number, Date or Interval property, we just sort the
+ scalar value of the property. Strings are sorted case-sensitively.
+2. If it's a Link property, we sort by either the linked item's "order"
+ property (if it has one) or the linked item's "id".
+3. Mulitlinks sort similar to #2, but we start with the first
+ Multilink list item, and if they're the same, we sort by the second item,
+ and so on.
- cat issue.txt | /usr/local/bin/roundup-mailgw /home/roundup
+Note that if an "order" property is defined on a Class that is used for
+sorting, all items of that Class *must* have a value against the "order"
+property, or sorting will result in random ordering.
- If that doesn't raise any errors, the problem is the permissions of the
- MTA.
+.. _`customisation`: customizing.html