=============== Getting Started =============== :Version: $Revision: 1.7 $ .. 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 TRACKER_WEB The web address of the issue tracker's web interface The email addresses used by the system by default are: 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 ``" 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 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 mailbox 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 pop 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 - ``TRACKER_HOMES`` needs to know about your tracker. You may also specify the values for ``TRACKER_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 "``//index``" where tracker name is the name you nominated in ``TRACKER_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 - ``TRACKER_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 ``TRACKER_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 TRACKER_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 TRACKER_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 ...//newuser to bring up a form which may be used to add a new user. 2. On the command-line, use:: roundup-admin -i 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 ...//newissue to bring up a form which may be used to add a new issue. 2. On the command-line, use:: roundup-admin -i 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