more Log removal

[roundup.git] / doc / getting_started.txt

===============
Getting Started
===============

:Version: $Revision: 1.6 $

.. contents::


The following instructions assume that you have installed roundup. If you
haven't, you may still proceed - just run the commands as
"``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for
``roundup-admin`` and
"``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
``roundup-server``.

The Tracker
-----------

We'll be referring to the term tracker a lot from now on. A tracker 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:

Hyperdatabase
   This is the lowest component of Roundup and is where all the issues,
   users, file attachments and messages are stored.

Database schema
   This describes the content of the hyperdatabase - what fields are stored
   for issues, what user information, etc. Being stored in the tracker,
   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
   tracker.

Web Interface
   The web interface templates are defined in the tracker 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
   tracker in use.

Trackers are created using the ``roundup-admin`` tool.

Command Line Tool
-----------------

To set up a new tracker, run "``roundup-admin install``". You will be
asked a few questions:

1. Tracker home directory
2. Schema to use
3. Database back-end to use

Once you've chosen these, roundup will install the tracker for you. It will
then indicate that you should configure some more information in the
file "``config.py``" in the tracker home.  It
should be edited before roundup is initialised, and may have the following
variable declarations:

MAILHOST
   The SMTP mail host that roundup will use to send mail
MAIL_DOMAIN
   The domain name used for email addresses
ISSUE_TRACKER_WEB
   The web address of the issue tracker's web interface

The email addresses used by the system by default are:

ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN``
   submissions of issues

ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN``
   roundup's internal use (problems, etc)

You may also alter the default schema - see the `customisation`_ documentation
for more info on both configuration variables and schema modifications.

Once you're happy (and note that you can change any of this after the tracker
is initialised too!) you must run "``roundup-admin initialise``".

You should also think about whether there is going to be controlled access
to the
tracker on the machine the tracker is running on. That is, who can
actually make
changes to the database using the roundup-admin tool. See the section on
Users_and_Access_Control for information on how to secure your tracker from the
start.

E-Mail Interface
----------------

Setup 1: As a mail alias pipe process 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Set up a mail alias called "issue_tracker" as (include the quote marks):
"``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_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 <tracker_home>
 
To test the mail gateway on unix systems, try::

    echo test |mail -s '[issue] test' issue_tracker@your.domain


Setup 2: As a regular cron job using a mailbox source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::

  10 * * * * /usr/local/bin/roundup-mailgw <tracker_home> mailbox <mail_spool_file>

Where the ``mail_spool_file`` argument is the location of the roundup submission
user's mail spool. On most systems, the spool for a user "issue_tracker"
will be "``/var/mail/issue_tracker``".

Setup 3: As a regular cron job using a POP source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::

  10 * * * * /usr/local/bin/roundup-mailgw <tracker_home> pop <pop_spec>
    
where pop_spec is "``username:password@server``" that specifies the roundup
submission user's POP account name, password and server.


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 tracker. You may also specify the values for
     ``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs.
    
  2. "``roundup-server [-p port] (name=tracker_home)*``" (hostname may be "")
  
  3. Load up the page "``/<tracker name>/index``" where tracker name is the name
     you nominated in ``ROUNDUP_INSTANCE_HOMES``.

Apache:
  1. The CGI script is found in the cgi-bin directory of the roundup
     distribution.
     
  2. Make sure roundup.cgi is executable. Edit it at the top -
     ``ROUNDUP_INSTANCE_HOMES`` needs to know about your tracker.
     
  3. 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.
     
  4. Re-start your apache to re-load the config if necessary.
  
  5. Load up the page "``/roundup/roundup.cgi/index/``" where tracker name is the
     name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
     
  6. To use the CGI script unchanged, which allows much easier updates, add
     these directives to your "httpd.conf"::
     
          SetEnv ROUNDUP_LOG "/var/log/roundup.log"
          SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/trackers/Default"
          SetEnv ROUNDUP_DEBUG "0"

  7. On Windows, write a batch file "roundup.bat" similar to the one below and
     place it into your cgi-bin directory::
      
          @echo off
          set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
          set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\trackers\Default;
          set ROUNDUP_DEBUG=0
          c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi


Users 
-----

Users and permissions
~~~~~~~~~~~~~~~~~~~~~

By default, roundup automatically creates one user when the tracker database is
initialised (using roundup-admin init). The user is "admin" and the password is
the one you supply at that time.

If users attempt to use roundup in any manner and are not identified to roundup,
they will be using the database in a read-only mode. That is, if roundup doesn't
know who they are, they can't change anything. This has the following
repurcussions:

Command-line interface
    The data modification commands (create, init, retire, set) are performed
    as the "admin" user. It is therefore important that the database be
    protected by the filesystem if protection is required. On a Unix system,
    the easiest and most flexible method of doing so is:

    1. Add a new user and group to your system (e.g. "issue_tracker")
    
    2. When creating a new tracker home, use the following commands
       (substituting tracker_home for the directory you want to use)::
        
            mkdir tracker_home
            chown issue_tracker:issue_tracker tracker_home
            chmod g+rwxs tracker_home
            roundup-admin -i tracker_home init
        
    3. Now, edit the /etc/group line for the issue_tracker group so it
       includes the unix logins of all the users who are going to
       administer your roundup tracker. If you're running the web or mail
       gateways, then be sure to include those users in the group too (on
       some Linux systems, these users are "www" or "apache" and "mail".)
       
E-Mail interface
    Users are identified by e-mail address - a new user entry will be created
    for any e-mail address that is not recognised, so users are always
    identified by roundup.

Web interface
    Unidentified users have read-only access. If the users database has an
    entry with the username "anonymous", then unidentified users are
    automatically logged in as that user. This gives them write access.

**anonymous access and the ANONYMOUS_* configurations.**


Adding users
~~~~~~~~~~~~

To add users, use one of the following interfaces:
  
1. On the web, access the URL .../<tracker 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 <tracker 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 .../<tracker 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 <tracker 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.

-----------------

Back to `Table of Contents`_

Next: `User Guide`_

.. _`table of contents`: index.html
.. _`user guide`: user_guide.html
.. _`customisation`: customizing.html