From: richard Date: Sat, 29 Sep 2001 13:09:32 +0000 (+0000) Subject: Started working on some _real_ documentation! X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=702a6a573b6226cd30d8c9ed6ec2bbd439cc82ac;p=roundup.git Started working on some _real_ documentation! git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@259 57a73879-2fb5-44c3-a270-3262357dd7e2 --- diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..571dcf7 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,249 @@ + +Roundup: an Issue-Tracking System for Knowledge Workers + + +

Roundup

+

An Issue-Tracking System for Knowledge Workers

+ +

Contents

+ + + +

+

Installation

+ + +

Prerequisites

+ +
+
Either: +
Python 2.0 with pydoc installed. See http://www.lfw.org/ for pydoc. +
or +
Python 2.1 or later +
+ +Download the latest version from +http://www.python.org/. + + + +

Getting Roundup

+ +Download the latest version from +http://roundup.sf.net/. + + +

Installing Roundup

+ +
    +
  1. Run: +
    python setup.py install +
  2. If you would prefer the scripts installed in somewhere other than + /usr/local/bin, add "--install-scripts=<dir>" + to the command: +
    python setup.py install --install-scripts=<dir> +
  3. The command: +
    python setup.py install --help +
    gives all the options available for installation. +
+ + +

+

Getting Started

+ +The following instructions assume that you have installed roundup. If you +haven't, you may still proceed - just preface all commands with "./" +ie. "./roundup-admin init". + + +

The Instance

+ +We'll be referring to the term "instance" a lot from now on. An instance is +a directory in your filesystem that is where all the information about a +live issue tracker database is stored. The data that is entered as issues, +the users who access the database and the definition of the database itself +all reside there: +
    +
  1. Hyperdatabase +
    This is the lowest component of Roundup and is where all the + issues, users, file attachments and messages are stored. +
  2. Database schema +
    This describes the content of the hyperdatabase - what fields are + stored for issues, what user information, etc. Being stored in the + instance, this allows it to be customised for a particular application. + It also means that changes in the Roundup core code do not affect a + running instance. +
  3. Web Interface +
    The web interface templates are defined in the instance too - and + the actual CGI interface class is defined (mostly using base classes in + the Roundup core code) so it, like the database, may be customised for + each instance in use. +
+ +Instances are created using the roundup-admin tool. + +

Command Line Tool

+ +To initiliase a new instance, run roundup-admin init. You will be +asked a series of questions: + +
    +
  1. Instance home directory +
  2. Schema to use +
  3. Database back-end to use +
  4. Administration user "admin" password. +
+ +Roundup is configurable using a localconfig.py file in the instance home. +It may have the following variable declarations: + +
    +
  1. MAILHOST +
    The SMTP mail host that roundup will use to send mail +
  2. MAIL_DOMAIN +
    The domain name used for email addresses +
+ +Any further configuration should be possible by editing the instance home's +__init__.py directly. +

+The email addresses used by the system by default are: + +

    +
  1. issue_tracker@MAIL_DOMAIN +
    submissions of issues +
  2. roundup-admin@MAIL_DOMAIN +
    roundup's internal use (problems, etc) +
+ +Note: +We run the instance as group "issue_tracker" and add the mail and web user +("mail" and "apache" on our RedHat 7.1 system) to that group, as well as +any admin people. + + +

E-Mail Interface

+Set up a mail alias called "issue_tracker" as: +
+ |/usr/bin/python /usr/local/bin/roundup-mailgw + <instance_home> +
+ +In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh +so sendmail will accept the pipe command. In that case, symlink +/etc/smrsh/roundup-mailgw to /usr/local/bin/roundup-mailgw and change the +command to: +
+ |roundup-mailgw <instance_home> +
+ +To test the mail gateway on unix systems, try: + +
+ echo test |mail -s '[issue] test' issue_tracker@your.domain +
+ + + +

Web Interface

+This software will work through apache or stand-alone. +

+Stand-alone: +

    +
  1. Edit roundup-server at the top - ROUNDUP_INSTANCE_HOMES needs to know + about your instance. *** command-line option +
  2. roundup-server [hostname port] (hostname may be "") +
  3. Load up the page /<instance name>/index where + instance name is the + name you nominated in ROUNDUP_INSTANCE_HOMES. +*** command-line option +
+ +Apache: +
    +
  1. Make sure roundup.cgi is executable. Edit it at the top - + ROUNDUP_INSTANCE_HOMES needs to know about your instance. +
  2. Edit your /etc/httpd/conf/httpd.conf and make sure that the + /home/httpd/html/roundup/roundup.cgi script will be treated as a CGI + script. +
  3. Add the following to your /etc/httpd/conf/httpd.conf: +
    +------8<------- snip here ------8<-------
+RewriteEngine on
+RewriteCond %{HTTP:Authorization} ^(.*)
+RewriteRule ^/roundup/roundup.cgi(.*) /home/httpd/html/roundup/roundup.cgi$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l]
+------8<------- snip here ------8<-------
+
    + note: the RewriteRule must be on one line - no breaks +
  4. Re-start your apache to re-load the config +
  5. Load up the page /roundup/roundup.cgi/<instance name>/index where + instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES. +
+ + +

Users

+To add users, use one of the following interfaces: + +
    +
  1. On the web, access the URL .../<instance name>/newuser + to bring up a form which may be used to add a new user. +
  2. On the command-line, use: +
    roundup-admin -i <instance home> create user + username=bozo password=bozo address=richard@clown.org +
    Supply the admin username and password. roundup-admin will print the + id of the new user. +
  3. Any e-mail sent to roundup from an address that doesn't match an + existing user in the database will result in a new user entry being + created for that user. +
+ + + +

Issues

+To add issues, use one of the following interfaces: + +
    +
  1. On the web, access the URL .../<instance name>/newissue + to bring up a form which may be used to add a new issue. +
  2. On the command-line, use: +
    roundup-admin -i <instance home> create issue + title="test issue" +
    Supply the admin username and password. roundup-admin will print the + id of the new issue. +
  3. Any e-mail sent to roundup with the subject line containing [issue] + will automatically created a new issue in the database using the + contents of the e-mail. +
+ +

+

Acknowledgements

+ +Go Ping, you rock! Also, go Bizar Software for letting me implement this +system on their time. + +