I just finished setting up a Roundup instance a few weeks ago.  Everything went pretty smoothly until I tried to log in.  After a long time debugging (more than an hour, hacking the roundup code, inserting print statements to trace execution) I found that I had misunderstood the tracker "name" option.  This is really poorly explained in the documentation, IMHO.  Worse, when set wrong Roundup did not produce any errors, it just won't let me login.

Note that I was using roundup-server as the web interface.  I think the source of the problem is that roundup was issuing a redirect instead of displaying an error or setting the login cookie.

I'm not sure which name you're referring to. Is it the one in the [tracker] section of the tracker's config.ini? That's purely cosmetic AFAIK. The [rdbms] name can't be the one you mean as that would result in a database error. If it's the "name=tracker home" argument to the roundup-server command-line, please give me some hint as to how I could improve upon the help message:

How to use "name=tracker home":
   These arguments set the tracker home(s) to use. The name is how the
   tracker is identified in the URL (it's the first part of the URL path).
   The tracker home is the directory that was identified when you did
   "roundup-admin init". You may specify any number of these name=home
   pairs on the command-line. Make sure the name part doesn't include
   any url-unsafe characters like spaces, as these confuse IE.

I think the initial source of confusion was how the man page was formatted.   It was something like:

<b>roundup-server</b>  [options] [<b>name=</b>tracker home]*

I assumed that meant you could do something like "roundup-server name=/home1 name=/home2".  IOW, it was not clear that "name" was variable, not literal.  That seemed logical to me since with just the home directory the config file could be parsed and the URL for the tracker found.

Aside for the formatting (maybe that's just my man implementation or my terminal), I guess the documentation is okay.  What about the "web" setting in the config file?  Does that need to match the path used for "name"?

Perhaps the easiest "fix" would be to print a warning in the log when the "name" or "web" setting does not match the request headers.  In my case I had no idea I had configured something wrong, just that I couldn't login.  Another idea would be to do away with the name variable passed to roundup-server and use the "web" URL from the config to figure things out.

I don't think we can use the request headers. If we're behind a proxy like Apache or lighttpd (which is probably how most people run roundup) the request headers are irrelevant. Your config.TRACKER_NAME will be something like "http://mainserver/bugs" and the request headers will look like:

HTTP_HOST = localhost:54321
SERVER_NAME = localhost
SERVER_PORT = 54321

We'd have to have access to the http configuration to truly validate config.TRACKER_NAME against the request headers.

I have, however, tried to clarify the roundup-server man page slightly and added an EXAMPLE section that will hopefully make it more obvious how the name=tracker_instance stuff is used.

I've checked that change into CVS. If you have suggestions about how to improve it further, please let me know.