=============== Getting Started =============== :Version: $Revision: 1.3 $ .. 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 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: 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 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. 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. You should also think about whether there is going to be controlled access to the instance on the machine the instance 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 instance from the start. Roundup is configurable using an ``instance_config.py`` file in the instance home. It should be edited before roundup is used, 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) 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 - ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance. You may also specify the values for ``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs. 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "") 3. Load up the page "``//index``" where instance 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 instance. 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 instance 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/instances/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\instances\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 instance 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 instance home, use the following commands (substituting instance_home for the directory you want to use):: mkdir instance_home chown issue_tracker:issue_tracker instance_home chmod g+rwxs instance_home roundup-admin -i instance_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 instance. 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