<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Installing Roundup &mdash; Roundup v1.4 documentation</title>
<link rel="stylesheet" href="_static/style.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '1.4',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="Roundup v1.4 documentation" href="index.html" />
<link rel="next" title="Upgrading to newer versions of Roundup" href="upgrading.html" />
<link rel="prev" title="Roundup Features" href="features.html" />
</head>
<body>
<div class="header"><h1>Roundup</h1>
<div id="searchbox" style="display: none">
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
<div class="navigation">
<div class="menu">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Installing Roundup</a><ul>
<li><a class="reference external" href="#overview">Overview</a></li>
<li><a class="reference external" href="#prerequisites">Prerequisites</a></li>
<li><a class="reference external" href="#optional-components">Optional Components</a></li>
<li><a class="reference external" href="#getting-roundup">Getting Roundup</a></li>
<li><a class="reference external" href="#for-the-really-impatient">For The Really Impatient</a></li>
<li><a class="reference external" href="#installation">Installation</a><ul>
<li><a class="reference external" href="#basic-installation-steps">Basic Installation Steps</a></li>
<li><a class="reference external" href="#configuring-your-first-tracker">Configuring your first tracker</a></li>
<li><a class="reference external" href="#choosing-your-template">Choosing Your Template</a><ul>
<li><a class="reference external" href="#classic-template">Classic Template</a></li>
<li><a class="reference external" href="#minimal-template">Minimal Template</a></li>
</ul>
</li>
<li><a class="reference external" href="#choosing-your-backend">Choosing Your Backend</a></li>
<li><a class="reference external" href="#configure-a-web-interface">Configure a Web Interface</a><ul>
<li><a class="reference external" href="#web-server-cgi-bin">Web Server cgi-bin</a></li>
<li><a class="reference external" href="#cgi-bin-for-limited-access-hosting">CGI-bin for Limited-Access Hosting</a></li>
<li><a class="reference external" href="#stand-alone-web-server">Stand-alone Web Server</a></li>
<li><a class="reference external" href="#zope-product-zroundup">Zope Product - ZRoundup</a></li>
<li><a class="reference external" href="#apache-http-server-with-mod-python">Apache HTTP Server with mod_python</a></li>
<li><a class="reference external" href="#wsgi-handler">WSGI Handler</a></li>
</ul>
</li>
<li><a class="reference external" href="#configure-an-email-interface">Configure an Email Interface</a><ul>
<li><a class="reference external" href="#as-a-mail-alias-pipe-process">As a mail alias pipe process</a></li>
<li><a class="reference external" href="#as-a-custom-router-transport-using-a-pipe-process-exim4-specific">As a custom router/transport using a pipe process (Exim4 specific)</a></li>
<li><a class="reference external" href="#as-a-regular-job-using-a-mailbox-source">As a regular job using a mailbox source</a></li>
<li><a class="reference external" href="#as-a-regular-job-using-a-pop-source">As a regular job using a POP source</a></li>
<li><a class="reference external" href="#as-a-regular-job-using-an-imap-source">As a regular job using an IMAP source</a></li>
</ul>
</li>
<li><a class="reference external" href="#unix-environment-steps">UNIX Environment Steps</a></li>
<li><a class="reference external" href="#additional-language-codecs">Additional Language Codecs</a></li>
<li><a class="reference external" href="#public-tracker-considerations">Public Tracker Considerations</a></li>
</ul>
</li>
<li><a class="reference external" href="#maintenance">Maintenance</a></li>
<li><a class="reference external" href="#upgrading">Upgrading</a></li>
<li><a class="reference external" href="#further-reading">Further Reading</a></li>
<li><a class="reference external" href="#running-multiple-trackers">Running Multiple Trackers</a></li>
<li><a class="reference external" href="#platform-specific-notes">Platform-Specific Notes</a><ul>
<li><a class="reference external" href="#windows-command-line-tools">Windows command-line tools</a></li>
<li><a class="reference external" href="#windows-server">Windows Server</a><ul>
<li><a class="reference external" href="#using-the-windows-scheduler">1. Using the Windows scheduler</a></li>
<li><a class="reference external" href="#installing-the-roundup-server-as-a-windows-service">2. Installing the roundup server as a Windows service</a></li>
</ul>
</li>
<li><a class="reference external" href="#sendmail-smrsh">Sendmail smrsh</a></li>
<li><a class="reference external" href="#linux">Linux</a></li>
<li><a class="reference external" href="#solaris">Solaris</a></li>
</ul>
</li>
<li><a class="reference external" href="#problems-testing-your-python">Problems? Testing your Python...</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="features.html"
title="previous chapter">Roundup Features</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="upgrading.html"
title="next chapter">Upgrading to newer versions of Roundup</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/installation.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p style="font-size: 90%">Enter search terms or a module, class or function name.</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="content">
<div class="related related-top">
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="upgrading.html" title="Upgrading to newer versions of Roundup"
accesskey="N">next</a></li>
<li class="right" >
<a href="features.html" title="Roundup Features"
accesskey="P">previous</a></li>
<li><a href="index.html">Roundup v1.4 documentation</a></li>
</ul>
</div>
<div class="section" id="installing-roundup">
<h1><a class="toc-backref" href="#id3">Installing Roundup</a></h1>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#installing-roundup" id="id3">Installing Roundup</a><ul>
<li><a class="reference internal" href="#overview" id="id4">Overview</a></li>
<li><a class="reference internal" href="#prerequisites" id="id5">Prerequisites</a></li>
<li><a class="reference internal" href="#optional-components" id="id6">Optional Components</a></li>
<li><a class="reference internal" href="#getting-roundup" id="id7">Getting Roundup</a></li>
<li><a class="reference internal" href="#for-the-really-impatient" id="id8">For The Really Impatient</a></li>
<li><a class="reference internal" href="#installation" id="id9">Installation</a></li>
<li><a class="reference internal" href="#maintenance" id="id10">Maintenance</a></li>
<li><a class="reference internal" href="#upgrading" id="id11">Upgrading</a></li>
<li><a class="reference internal" href="#further-reading" id="id12">Further Reading</a></li>
<li><a class="reference internal" href="#running-multiple-trackers" id="id13">Running Multiple Trackers</a></li>
<li><a class="reference internal" href="#platform-specific-notes" id="id14">Platform-Specific Notes</a></li>
<li><a class="reference internal" href="#problems-testing-your-python" id="id15">Problems? Testing your Python...</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="overview">
<h2><a class="toc-backref" href="#id4">Overview</a></h2>
<p>Broken out separately, there are several conceptual pieces to a
Roundup installation:</p>
<dl class="docutils">
<dt>Roundup trackers</dt>
<dd>Trackers consist of issues (be they bug reports or otherwise), tracker
configuration file(s), web HTML files etc. Roundup trackers are initialised
with a “Template” which defines the fields usable/assignable on a
per-issue basis. Descriptions of the provided templates are given in
<a class="reference internal" href="#choosing-your-template">choosing your template</a>.</dd>
<dt>Roundup support code</dt>
<dd>Installed into your Python install’s lib directory.</dd>
<dt>Roundup scripts</dt>
<dd>These include the email gateway, the roundup
HTTP server, the roundup administration command-line interface, etc.</dd>
</dl>
</div>
<div class="section" id="prerequisites">
<h2><a class="toc-backref" href="#id5">Prerequisites</a></h2>
<p>Roundup requires Python 2.3 or newer (but not Python 3) with a functioning
anydbm module. Download the latest version from <a class="reference external" href="http://www.python.org/">http://www.python.org/</a>.
It is highly recommended that users install the latest patch version
of python as these contain many fixes to serious bugs.</p>
<p>Some variants of Linux will need an additional “python dev” package
installed for Roundup installation to work. Debian and derivatives, are
known to require this.</p>
<p>If you’re on windows, you will either need to be using the ActiveState python
distribution (at <a class="reference external" href="http://www.activestate.com/Products/ActivePython/">http://www.activestate.com/Products/ActivePython/</a>), or you’ll
have to install the win32all package separately (get it from
<a class="reference external" href="http://starship.python.net/crew/mhammond/win32/">http://starship.python.net/crew/mhammond/win32/</a>).</p>
</div>
<div class="section" id="optional-components">
<h2><a class="toc-backref" href="#id6">Optional Components</a></h2>
<p>You may optionally install and use:</p>
<dl class="docutils">
<dt>Timezone Definitions</dt>
<dd>Full timezone support requires <a class="reference external" href="http://www.python.org/pypi/pytz">pytz</a> module (version 2005i or later)
which brings the <a class="reference external" href="http://www.twinsun.com/tz/tz-link.htm">Olson tz database</a> into Python. If <a class="reference external" href="http://www.python.org/pypi/pytz">pytz</a> is not
installed, timezones may be specified as numeric hour offsets only.</dd>
<dt>An RDBMS</dt>
<dd>Sqlite, MySQL and Postgresql are all supported by Roundup and will be
used if available. One of these is recommended if you are anticipating a
large user base (see <a class="reference internal" href="#choosing-your-backend">choosing your backend</a> below).</dd>
<dt>Xapian full-text indexer</dt>
<dd><p class="first">The <a class="reference external" href="http://xapian.org/">Xapian</a> full-text indexer is also supported and will be used by
default if it is available. This is strongly recommended if you are
anticipating a large number of issues (> 5000).</p>
<p>You may install Xapian at any time, even after a tracker has been
installed and used. You will need to run the “roundup-admin reindex”
command if the tracker has existing data.</p>
<p class="last">Roundup requires Xapian 1.0.0 or newer.</p>
</dd>
<dt>pyopenssl</dt>
<dd>If <a class="reference external" href="http://pyopenssl.sourceforge.net">pyopenssl</a> is installed the roundup-server can be configured
to serve trackers over SSL. If you are going to serve roundup via
proxy through a server with SSL support (e.g. apache) then this is
unnecessary.</dd>
<dt>pyme</dt>
<dd>If <a class="reference external" href="http://pyme.sourceforge.net">pyme</a> is installed you can configure the mail gateway to perform
verification or decryption of incoming OpenPGP MIME messages. When
configured, you can require email to be cryptographically signed
before roundup will allow it to make modifications to issues.</dd>
</dl>
</div>
<div class="section" id="getting-roundup">
<h2><a class="toc-backref" href="#id7">Getting Roundup</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Some systems, such as Debian and NetBSD, already have Roundup
installed. Try running the command “roundup-admin” with no arguments,
and if it runs you may skip the <a class="reference internal" href="#basic-installation-steps">Basic Installation Steps</a>
below and go straight to <a class="reference internal" href="#configuring-your-first-tracker">configuring your first tracker</a>.</p>
</div>
<p>Download the latest version from <a class="reference external" href="http://roundup.sf.net/">http://roundup.sf.net/</a>.</p>
<p>If you’re using WinZIP’s “classic” interface, make sure the “Use
folder names” check box is checked before you extract the files.</p>
</div>
<div class="section" id="for-the-really-impatient">
<h2><a class="toc-backref" href="#id8">For The Really Impatient</a></h2>
<p>If you just want to give Roundup a whirl Right Now, then simply run
<tt class="docutils literal"><span class="pre">roundup-demo</span></tt>.</p>
<p>This will set up a simple demo tracker on your machine. <a class="footnote-reference" href="#id2" id="id1">[1]</a>
When it’s done, it’ll print out a URL to point your web browser at
so you may start playing. Three users will be set up:</p>
<ol class="arabic simple">
<li>anonymous - the “default” user with permission to do very little</li>
<li>demo (password “demo”) - a normal user who may create issues</li>
<li>admin (password “admin”) - an administrative user who has complete
access to the tracker</li>
</ol>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Demo tracker is set up to be accessed by localhost browser.
If you run demo on a server host, please stop the demo when
it has shown startup notice, open file <tt class="docutils literal"><span class="pre">demo/config.ini</span></tt> with
your editor, change host name in the <tt class="docutils literal"><span class="pre">web</span></tt> option in section
<tt class="docutils literal"><span class="pre">[tracker]</span></tt>, save the file, then re-run the demo program.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="installation">
<h2><a class="toc-backref" href="#id9">Installation</a></h2>
<p>Set aside 15-30 minutes. There’s several steps to follow in your
installation:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#basic-installation-steps">basic installation steps</a> if Roundup is not installed on your system</li>
<li><a class="reference internal" href="#configuring-your-first-tracker">configuring your first tracker</a> that all installers must follow</li>
<li>then optionally <a class="reference internal" href="#configure-a-web-interface">configure a web interface</a></li>
<li>and optionally <a class="reference internal" href="#configure-an-email-interface">configure an email interface</a></li>
<li><a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a> to take if you’re installing on a shared
UNIX machine and want to restrict local access to roundup</li>
<li><a class="reference internal" href="#additional-language-codecs">additional language codecs</a></li>
</ol>
<p>For information about how Roundup installs, see the <a class="reference external" href="admin_guide.html">administration
guide</a>.</p>
<div class="section" id="basic-installation-steps">
<h3>Basic Installation Steps</h3>
<p>To install the Roundup support code into your Python tree and
Roundup scripts into /usr/bin (substitute that path for whatever is
appropriate on your system). You need to have write permissions
for these locations, eg. being root on unix:</p>
<div class="highlight-python"><pre>python setup.py install</pre>
</div>
<p>If you would like to place the Roundup scripts in a directory other
than <tt class="docutils literal"><span class="pre">/usr/bin</span></tt>, then specify the preferred location with
<tt class="docutils literal"><span class="pre">--install-scripts</span></tt>. For example, to install them in
<tt class="docutils literal"><span class="pre">/opt/roundup/bin</span></tt>:</p>
<div class="highlight-python"><pre>python setup.py install --install-scripts=/opt/roundup/bin</pre>
</div>
<p>You can also use the <tt class="docutils literal"><span class="pre">--prefix</span></tt> option to use a completely different
base directory, if you do not want to use administrator rights. If you
choose to do this, you may have to change Python’s search path (sys.path)
yourself.</p>
</div>
<div class="section" id="configuring-your-first-tracker">
<h3>Configuring your first tracker</h3>
<ol class="arabic">
<li><p class="first">To create a Roundup tracker (necessary to do before you can
use the software in any real fashion), you need to set up a “tracker
home”:</p>
<ol class="loweralpha">
<li><p class="first">(Optional) If you intend to keep your roundup trackers
under one top level directory which does not exist yet,
you should create that directory now. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mkdir</span> <span class="o">/</span><span class="n">opt</span><span class="o">/</span><span class="n">roundup</span><span class="o">/</span><span class="n">trackers</span>
</pre></div>
</div>
</li>
<li><p class="first">Either add the Roundup script location to your <tt class="docutils literal"><span class="pre">PATH</span></tt>
environment variable or specify the full path to
the command in the next step.</p>
</li>
<li><p class="first">Install a new tracker with the command <tt class="docutils literal"><span class="pre">roundup-admin</span> <span class="pre">install</span></tt>.
You will be asked a series of questions. Descriptions of the provided
templates can be found in <a class="reference internal" href="#choosing-your-template">choosing your template</a> below. Descriptions
of the available backends can be found in <a class="reference internal" href="#choosing-your-backend">choosing your backend</a>
below. The questions will be something like (you may have more
templates or backends available):</p>
<div class="highlight-python"><pre>Enter tracker home: /opt/roundup/trackers/support
Templates: classic
Select template [classic]: classic
Back ends: anydbm, mysql, sqlite
Select backend [anydbm]: anydbm</pre>
</div>
<p>Note: “Back ends” selection list depends on availability of
third-party database modules. Standard python distribution
includes anydbm module only.</p>
<p>The “support” part of the tracker name can be anything you want - it
is going to be used as the directory that the tracker information
will be stored in.</p>
<p>You will now be directed to edit the tracker configuration and
initial schema. At a minimum, you must set “main :: admin_email”
(that’s the “admin_email” option in the “main” section) “mail ::
host”, “tracker :: web” and “mail :: domain”. If you get stuck,
and get configuration file errors, then see the <a class="reference external" href="customizing.html#tracker-configuration">tracker
configuration</a> section of the <a class="reference external" href="customizing.html">customisation documentation</a>.</p>
<p>If you just want to get set up to test things quickly (and follow
the instructions in step 3 below), you can even just set the
“tracker :: web” variable to:</p>
<div class="highlight-python"><pre>web = http://localhost:8080/support/</pre>
</div>
<p>The URL <em>must</em> end in a ‘/’, or your web interface <em>will not work</em>.
See <a class="reference external" href="customizing.html">Customising Roundup</a> for details on configuration and schema
changes. You may change any of the configuration after
you’ve initialised the tracker - it’s just better to have valid values
for this stuff now.</p>
</li>
<li><p class="first">Initialise the tracker database with <tt class="docutils literal"><span class="pre">roundup-admin</span> <span class="pre">initialise</span></tt>.
You will need to supply an admin password at this step. You will be
prompted:</p>
<div class="highlight-python"><pre>Admin Password:
Confirm:</pre>
</div>
<p>Note: running this command will <em>destroy any existing data in the
database</em>. In the case of MySQL and PostgreSQL, any existing database
will be dropped and re-created.</p>
<p>Once this is done, the tracker has been created.</p>
</li>
</ol>
</li>
<li><p class="first">At this point, your tracker is set up, but doesn’t have a nice user
interface. To set that up, we need to <a class="reference internal" href="#configure-a-web-interface">configure a web interface</a> and
optionally <a class="reference internal" href="#configure-an-email-interface">configure an email interface</a>. If you want to try your
new tracker out, assuming “tracker :: web” is set to
<tt class="docutils literal"><span class="pre">'http://localhost:8080/support/'</span></tt>, run:</p>
<div class="highlight-python"><pre>roundup-server support=/opt/roundup/trackers/support</pre>
</div>
<p>then direct your web browser at:</p>
<blockquote>
<p><a class="reference external" href="http://localhost:8080/support/">http://localhost:8080/support/</a></p>
</blockquote>
<p>and you should see the tracker interface.</p>
</li>
</ol>
</div>
<div class="section" id="choosing-your-template">
<h3>Choosing Your Template</h3>
<div class="section" id="classic-template">
<h4>Classic Template</h4>
<p>The classic template is the one defined in the <a class="reference external" href="spec.html">Roundup Specification</a>. It
holds issues which have priorities and statuses. Each issue may also have a
set of messages which are disseminated to the issue’s list of nosy users.</p>
</div>
<div class="section" id="minimal-template">
<h4>Minimal Template</h4>
<p>The minimal template has the minimum setup required for a tracker
installation. That is, it has the configuration files, defines a user database
and the basic HTML interface to that. It’s a completely clean slate for you to
create your tracker on.</p>
</div>
</div>
<div class="section" id="choosing-your-backend">
<h3>Choosing Your Backend</h3>
<p>The actual storage of Roundup tracker information is handled by backends.
There’s several to choose from, each with benefits and limitations:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="20%" />
<col width="9%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Name</th>
<th class="head">Speed</th>
<th class="head">Users</th>
<th class="head">Support</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>anydbm</td>
<td>Slowest</td>
<td>Few</td>
<td>Always available</td>
</tr>
<tr><td>sqlite</td>
<td>Fastest(*)</td>
<td>Few</td>
<td>May need install (<a class="reference external" href="http://pysqlite.org/">PySQLite</a>)</td>
</tr>
<tr><td>postgresql</td>
<td>Fast</td>
<td>Many</td>
<td>Needs install/admin (<a class="reference external" href="http://initd.org/software/initd/psycopg">psycopg</a>)</td>
</tr>
<tr><td>mysql</td>
<td>Fast</td>
<td>Many</td>
<td>Needs install/admin (<a class="reference external" href="http://sourceforge.net/projects/mysql-python">MySQLdb</a>)</td>
</tr>
</tbody>
</table>
<dl class="docutils">
<dt><strong>sqlite</strong></dt>
<dd><p class="first">This uses the embedded database engine <a class="reference external" href="http://pysqlite.org/">PySQLite</a> to provide a very fast
backend. This is not suitable for trackers which will have many
simultaneous users, but requires much less installation and maintenance
effort than more scalable postgresql and mysql backends.</p>
<p>SQLite is supported via PySQLite versions 1.1.7, 2.1.0 and sqlite3 (the last
being bundled with Python 2.5+)</p>
<p class="last">Installed SQLite should be the latest version available (3.3.8 is known
to work, 3.1.3 is known to have problems).</p>
</dd>
<dt><strong>postgresql</strong></dt>
<dd>Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for
additional installation steps and requirements. You must also configure
the <tt class="docutils literal"><span class="pre">rdbms</span></tt> section of your tracker’s <tt class="docutils literal"><span class="pre">config.ini</span></tt>. It is recommended
that you use at least version 1.1.21 of psycopg.</dd>
<dt><strong>mysql</strong></dt>
<dd>Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
installation steps and requirements. You must also configure the <tt class="docutils literal"><span class="pre">rdbms</span></tt>
section of your tracker’s <tt class="docutils literal"><span class="pre">config.ini</span></tt></dd>
</dl>
<p>You may defer your decision by setting your tracker up with the anydbm
backend (which is guaranteed to be available) and switching to one of the
other backends at any time using the instructions in the <a class="reference external" href="admin_guide.html">administration
guide</a>.</p>
<p>Regardless of which backend you choose, Roundup will attempt to initialise
a new database for you when you run the roundup-admin “initialise” command.
In the case of MySQL and PostgreSQL you will need to have the appropriate
privileges to create databases.</p>
</div>
<div class="section" id="configure-a-web-interface">
<h3>Configure a Web Interface</h3>
<p>There are five web interfaces to choose from:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#web-server-cgi-bin">web server cgi-bin</a></li>
<li><a class="reference internal" href="#cgi-bin-for-limited-access-hosting">cgi-bin for limited-access hosting</a></li>
<li><a class="reference internal" href="#stand-alone-web-server">stand-alone web server</a></li>
<li><a class="reference internal" href="#zope-product-zroundup">Zope product - ZRoundup</a></li>
<li><a class="reference internal" href="#apache-http-server-with-mod-python">Apache HTTP Server with mod_python</a></li>
<li><a class="reference internal" href="#wsgi-handler">WSGI handler</a></li>
</ol>
<p>You may need to give the web server user permission to access the tracker home
- see the <a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a> for information. You may also need to
configure your system in some way - see <a class="reference internal" href="#platform-specific-notes">platform-specific notes</a>.</p>
<div class="section" id="web-server-cgi-bin">
<h4>Web Server cgi-bin</h4>
<p>A benefit of using the cgi-bin approach is that it’s the easiest way to
restrict access to your tracker to only use HTTPS. Access will be slower
than through the <a class="reference internal" href="#stand-alone-web-server">stand-alone web server</a> though.</p>
<p>If your Python isn’t installed as “python” then you’ll need to edit
the <tt class="docutils literal"><span class="pre">roundup.cgi</span></tt> script to fix the first line.</p>
<p>If you’re using IIS on a Windows platform, you’ll need to run this command
for the cgi to work (it turns on the PATH_INFO cgi variable):</p>
<div class="highlight-python"><pre>adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE</pre>
</div>
<p>The <tt class="docutils literal"><span class="pre">adsutil.vbs</span></tt> file can be found in either <tt class="docutils literal"><span class="pre">c:\inetpub\adminscripts</span></tt>
or <tt class="docutils literal"><span class="pre">c:\winnt\system32\inetsrv\adminsamples\</span></tt> or
<tt class="docutils literal"><span class="pre">c:\winnt\system32\inetsrv\adminscripts\</span></tt> depending on your installation.</p>
<p>More information about ISS setup may be found at:</p>
<blockquote>
<a class="reference external" href="http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B276494">http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B276494</a></blockquote>
<p>Copy the <tt class="docutils literal"><span class="pre">frontends/roundup.cgi</span></tt> file to your web server’s <tt class="docutils literal"><span class="pre">cgi-bin</span></tt>
directory. You will need to configure it to tell it where your tracker home
is. You can do this either:</p>
<dl class="docutils">
<dt>Through an environment variable</dt>
<dd>Set the variable TRACKER_HOMES to be a colon (“:”) separated list of
name=home pairs (if you’re using apache, the SetEnv directive can do this)</dd>
<dt>Directly in the <tt class="docutils literal"><span class="pre">roundup.cgi</span></tt> file itself</dt>
<dd>Add your instance to the TRACKER_HOMES variable as <tt class="docutils literal"><span class="pre">'name':</span> <span class="pre">'home'</span></tt></dd>
</dl>
<p>The “name” part of the configuration will appear in the URL and identifies the
tracker (so you may have more than one tracker per cgi-bin script). Make sure
there are no spaces or other illegal characters in it (to be safe, stick to
letters and numbers). The “name” forms part of the URL that appears in the
tracker config “tracker :: web” variable, so make sure they match. The “home”
part of the configuration is the tracker home directory.</p>
<p>If you’re using Apache, you can use an additional trick to hide the
<tt class="docutils literal"><span class="pre">.cgi</span></tt> extension of the cgi script. Place the <tt class="docutils literal"><span class="pre">roundup.cgi</span></tt> script
wherever you want it to be, rename it to just <tt class="docutils literal"><span class="pre">roundup</span></tt>, and add a
couple lines to your Apache configuration:</p>
<div class="highlight-python"><pre><Location /path/to/roundup>
SetHandler cgi-script
</Location></pre>
</div>
</div>
<div class="section" id="cgi-bin-for-limited-access-hosting">
<h4>CGI-bin for Limited-Access Hosting</h4>
<p>If you are running in a shared-hosting environment or otherwise don’t have
permissiong to edit the system web server’s configuration, but can create a
<tt class="docutils literal"><span class="pre">.htaccess</span></tt> file then you may be able to use this approach.</p>
<ol class="arabic">
<li><p class="first">Install <a class="reference external" href="http://pypi.python.org/pypi/flup">flup</a></p>
</li>
<li><p class="first">Create a script <tt class="docutils literal"><span class="pre">roundup_stub</span></tt> in your server’s <tt class="docutils literal"><span class="pre">cgi-bin</span></tt> directory
containing:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">#!/usr/bin/env python</span>
<span class="c"># if necessary modify the Python path to include the place you</span>
<span class="c"># installed Roundup</span>
<span class="c">#import sys</span>
<span class="c">#sys.path.append('...')</span>
<span class="c"># cgitb is needed for debugging in browser only</span>
<span class="c">#import cgitb</span>
<span class="c">#cgitb.enable()</span>
<span class="c"># obtain the WSGI request dispatcher</span>
<span class="kn">from</span> <span class="nn">roundup.cgi.wsgi_handler</span> <span class="kn">import</span> <span class="n">RequestDispatcher</span>
<span class="n">tracker_home</span> <span class="o">=</span> <span class="s">'/path/to/tracker/home'</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">RequestDispatcher</span><span class="p">(</span><span class="n">tracker_home</span><span class="p">)</span>
<span class="kn">from</span> <span class="nn">flup.server.cgi</span> <span class="kn">import</span> <span class="n">WSGIServer</span>
<span class="n">WSGIServer</span><span class="p">(</span><span class="n">app</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
</li>
<li><p class="first">Modify or created the <tt class="docutils literal"><span class="pre">.htaccess</span></tt> file in the desired (sub-)domain
directory to contain:</p>
<div class="highlight-python"><pre>RewriteEngine On
RewriteBase /
RewriteRule ^(.*)$ /cgi-bin/roundup_stub/$1 [L]</pre>
</div>
</li>
</ol>
<p>Now loading the (sub-)domain in a browser should load the tracker web
interface. If you get a “500” error then enable the “cgitb” lines in the
stub to get some debugging information.</p>
</div>
<div class="section" id="stand-alone-web-server">
<h4>Stand-alone Web Server</h4>
<p>This approach will give you faster response than cgi-bin. You may
investigate using ProxyPass or similar configuration in apache to have your
tracker accessed through the same URL as other systems.</p>
<p>The stand-alone web server is started with the command <tt class="docutils literal"><span class="pre">roundup-server</span></tt>. It
has several options - display them with <tt class="docutils literal"><span class="pre">roundup-server</span> <span class="pre">-h</span></tt>.</p>
<p>The tracker home configuration is similar to the cgi-bin - you may either edit
the script to change the TRACKER_HOMES variable or you may supply the
name=home values on the command-line after all the other options.</p>
<p>To make the server run in the background, use the “-d” option, specifying the
name of a file to write the server process id (pid) to.</p>
</div>
<div class="section" id="zope-product-zroundup">
<h4>Zope Product - ZRoundup</h4>
<p>ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
your Products directory either in INSTANCE_HOME/Products or the Zope
code tree lib/python/Products.</p>
<p>When you next (re)start up Zope, you will be able to add a ZRoundup object
that interfaces to your new tracker.</p>
</div>
<div class="section" id="apache-http-server-with-mod-python">
<h4>Apache HTTP Server with mod_python</h4>
<p><a class="reference external" href="http://www.modpython.org/">Mod_python</a> is an <a class="reference external" href="http://httpd.apache.org/">Apache</a> module that embeds the Python interpreter
within the server. Running Roundup this way is much faster than all
above options and, like <a class="reference internal" href="#web-server-cgi-bin">web server cgi-bin</a>, allows you to use HTTPS
protocol. The drawback is that this setup is more complicated.</p>
<p>The following instructions were tested on apache 2.0 with mod_python 3.1.
If you are using older versions, your mileage may vary.</p>
<p>Mod_python uses OS threads. If your apache was built without threads
(quite commonly), you must load the threading library to run mod_python.
This is done by setting <tt class="docutils literal"><span class="pre">LD_PRELOAD</span></tt> to your threading library path
in apache <tt class="docutils literal"><span class="pre">envvars</span></tt> file. Example for gentoo linux (<tt class="docutils literal"><span class="pre">envvars</span></tt> file
is located in <tt class="docutils literal"><span class="pre">/usr/lib/apache2/build/</span></tt>):</p>
<div class="highlight-python"><pre>LD_PRELOAD=/lib/libpthread.so.0
export LD_PRELOAD</pre>
</div>
<p>Example for FreeBSD (<tt class="docutils literal"><span class="pre">envvars</span></tt> is in <tt class="docutils literal"><span class="pre">/usr/local/sbin/</span></tt>):</p>
<div class="highlight-python"><pre>LD_PRELOAD=/usr/lib/libc_r.so
export LD_PRELOAD</pre>
</div>
<p>Next, you have to add Roundup trackers configuration to apache config.
Roundup apache interface uses the following options specified with
<tt class="docutils literal"><span class="pre">PythonOption</span></tt> directives:</p>
<blockquote>
<dl class="docutils">
<dt>TrackerHome:</dt>
<dd>defines the tracker home directory - the directory that was specified
when you did <tt class="docutils literal"><span class="pre">roundup-admin</span> <span class="pre">init</span></tt>. This option is required.</dd>
<dt>TrackerLanguage:</dt>
<dd>defines web user interface language. mod_python applications do not
receive OS environment variables in the same way as command-line
programs, so the language cannot be selected by setting commonly
used variables like <tt class="docutils literal"><span class="pre">LANG</span></tt> or <tt class="docutils literal"><span class="pre">LC_ALL</span></tt>. <tt class="docutils literal"><span class="pre">TrackerLanguage</span></tt>
value has the same syntax as values of these environment variables.
This option may be omitted.</dd>
<dt>TrackerDebug:</dt>
<dd>run the tracker in debug mode. Setting this option to <tt class="docutils literal"><span class="pre">yes</span></tt> or
<tt class="docutils literal"><span class="pre">true</span></tt> has the same effect as running <tt class="docutils literal"><span class="pre">roundup-server</span> <span class="pre">-t</span> <span class="pre">debug</span></tt>:
the database schema and used html templates are rebuilt for each
HTTP request. Values <tt class="docutils literal"><span class="pre">no</span></tt> or <tt class="docutils literal"><span class="pre">false</span></tt> mean that all html
templates for the tracker are compiled and the database schema is
checked once at startup. This is the default behaviour.</dd>
<dt>TrackerTiming:</dt>
<dd>has nearly the same effect as environment variable <tt class="docutils literal"><span class="pre">CGI_SHOW_TIMING</span></tt>
for standalone roundup server. The difference is that setting this
option to <tt class="docutils literal"><span class="pre">no</span></tt> or <tt class="docutils literal"><span class="pre">false</span></tt> disables timings display. Value
<tt class="docutils literal"><span class="pre">comment</span></tt> writes request handling times in html comment, and
any other non-empty value makes timing report visible. By default,
timing display is disabled.</dd>
</dl>
</blockquote>
<p>In the following example we have two trackers set up in
<tt class="docutils literal"><span class="pre">/var/db/roundup/support</span></tt> and <tt class="docutils literal"><span class="pre">/var/db/roundup/devel</span></tt> and accessed
as <tt class="docutils literal"><span class="pre">https://my.host/roundup/support/</span></tt> and <tt class="docutils literal"><span class="pre">https://my.host/roundup/devel/</span></tt>
respectively (provided Apache has been set up for SSL of course).
Having them share same parent directory allows us to
reduce the number of configuration directives. Support tracker has
russian user interface. The other tracker (devel) has english user
interface (default).</p>
<p>Static files from <tt class="docutils literal"><span class="pre">html</span></tt> directory are served by apache itself - this
is quicker and generally more robust than doing that from python.
Everything else is aliased to dummy (non-existing) <tt class="docutils literal"><span class="pre">py</span></tt> file,
which is handled by mod_python and our roundup module.</p>
<p>Example mod_python configuration:</p>
<div class="highlight-python"><pre>#################################################
# Roundup Issue tracker
#################################################
# enable Python optimizations (like 'python -O')
PythonOptimize On
# let apache handle static files from 'html' directories
AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2
# everything else is handled by roundup web UI
AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2
# roundup requires a slash after tracker name - add it if missing
RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/
# common settings for all roundup trackers
<Directory /var/db/roundup/*>
Order allow,deny
Allow from all
AllowOverride None
Options None
AddHandler python-program .py
PythonHandler roundup.cgi.apache
# uncomment the following line to see tracebacks in the browser
# (note that *some* tracebacks will be displayed anyway)
#PythonDebug On
</Directory>
# roundup tracker homes
<Directory /var/db/roundup/support>
PythonOption TrackerHome /var/db/roundup/support
PythonOption TrackerLanguage ru
</Directory>
<Directory /var/db/roundup/devel>
PythonOption TrackerHome /var/db/roundup/devel
</Directory></pre>
</div>
<p>Notice that the <tt class="docutils literal"><span class="pre">/var/db/roundup</span></tt> path shown above refers to the directory
in which the tracker homes are stored. The actual value will thus depend on
your system.</p>
<p>On Windows the corresponding lines will look similar to these:</p>
<div class="highlight-python"><pre>AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2
AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2
<Directory C:/DATA/roundup/*>
<Directory C:/DATA/roundup/support>
<Directory C:/DATA/roundup/devel></pre>
</div>
<p>In this example the directory hosting all of the tracker homes is
<tt class="docutils literal"><span class="pre">C:\DATA\roundup</span></tt>. (Notice that you must use forward slashes in paths
inside the httpd.conf file!)</p>
<p>The URL for accessing these trackers then become:
<cite>http://<roundupserver>/roundup/support/`</cite> and
<tt class="docutils literal"><span class="pre">http://<roundupserver>/roundup/devel/</span></tt></p>
<p>Note that in order to use https connections you must set up Apache for secure
serving with SSL.</p>
</div>
<div class="section" id="wsgi-handler">
<h4>WSGI Handler</h4>
<p>The WSGI handler is quite simple. The following sample code shows how
to use it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">wsgiref.simple_server</span> <span class="kn">import</span> <span class="n">make_server</span>
<span class="c"># obtain the WSGI request dispatcher</span>
<span class="kn">from</span> <span class="nn">roundup.cgi.wsgi_handler</span> <span class="kn">import</span> <span class="n">RequestDispatcher</span>
<span class="n">tracker_home</span> <span class="o">=</span> <span class="s">'demo'</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">RequestDispatcher</span><span class="p">(</span><span class="n">tracker_home</span><span class="p">)</span>
<span class="n">httpd</span> <span class="o">=</span> <span class="n">make_server</span><span class="p">(</span><span class="s">''</span><span class="p">,</span> <span class="mi">8917</span><span class="p">,</span> <span class="n">app</span><span class="p">)</span>
<span class="n">httpd</span><span class="o">.</span><span class="n">serve_forever</span><span class="p">()</span>
</pre></div>
</div>
<p>To test the above you should create a demo tracker with <tt class="docutils literal"><span class="pre">python</span> <span class="pre">demo.py</span></tt>.
Edit the <tt class="docutils literal"><span class="pre">config.ini</span></tt> to change the web URL to “<a class="reference external" href="http://localhost:8917/">http://localhost:8917/</a>“.</p>
</div>
</div>
<div class="section" id="configure-an-email-interface">
<h3>Configure an Email Interface</h3>
<p>If you don’t want to use the email component of Roundup, then remove the
“<tt class="docutils literal"><span class="pre">nosyreaction.py</span></tt>” module from your tracker “<tt class="docutils literal"><span class="pre">detectors</span></tt>” directory.</p>
<p>See <a class="reference internal" href="#platform-specific-notes">platform-specific notes</a> for steps that may be needed on your system.</p>
<p>There are five supported ways to get emailed issues into the
Roundup tracker. You should pick ONE of the following, all
of which will continue my example setup from above:</p>
<div class="section" id="as-a-mail-alias-pipe-process">
<h4>As a mail alias pipe process</h4>
<p>Set up a mail alias called “issue_tracker” as (include the quote marks):
“<tt class="docutils literal"><span class="pre">|/usr/bin/python</span> <span class="pre">/usr/bin/roundup-mailgw</span> <span class="pre"><tracker_home></span></tt>”
(substitute <tt class="docutils literal"><span class="pre">/usr/bin</span></tt> for wherever roundup-mailgw is installed).</p>
<p>In some installations (e.g. RedHat Linux and Fedora Core) you’ll need to
set up smrsh so sendmail will accept the pipe command. In that case,
symlink <tt class="docutils literal"><span class="pre">/etc/smrsh/roundup-mailgw</span></tt> to “<tt class="docutils literal"><span class="pre">/usr/bin/roundup-mailgw</span></tt>”
and change the command to:</p>
<div class="highlight-python"><pre>|roundup-mailgw /opt/roundup/trackers/support</pre>
</div>
<p>To test the mail gateway on unix systems, try:</p>
<div class="highlight-python"><pre>echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE</pre>
</div>
<p>Be careful that some mail systems (postfix for example) will impost a
limits on processes they spawn. In particular postfix can set a file size
limit. <em>This can cause your Roundup database to become corrupted.</em></p>
</div>
<div class="section" id="as-a-custom-router-transport-using-a-pipe-process-exim4-specific">
<h4>As a custom router/transport using a pipe process (Exim4 specific)</h4>
<p>The following configuration snippets for <a class="reference external" href="http://www.exim.org/">Exim 4</a> configuration
implement a custom router & transport to accomplish mail delivery to
roundup-mailgw. A configuration for Exim3 is similar but not
included, since Exim3 is considered obsolete.</p>
<p>This configuration is similar to the previous section, in that it uses
a pipe process. However, there are advantages to using a custom
router/transport process, if you are using Exim.</p>
<ul class="simple">
<li>This avoids privilege escalation, since otherwise the pipe process
will run as the mail user, typically mail. The transport can be
configured to run as the user appropriate for the task at hand. In the
transport described in this section, Exim4 runs as the unprivileged
user <tt class="docutils literal"><span class="pre">roundup</span></tt>.</li>
<li>Separate configuration is not required for each tracker
instance. When a email arrives at the server, Exim passes it through
the defined routers. The roundup_router looks for a match with one of
the roundup directories, and if there is one it is passed to the
roundup_transport, which uses the pipe process described in the
previous section (<a class="reference internal" href="#as-a-mail-alias-pipe-process">As a mail alias pipe process</a>).</li>
</ul>
<p>The matching is done in the line:</p>
<div class="highlight-python"><pre>require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py</pre>
</div>
<p>The following configuration has been tested on Debian Sarge with
Exim4.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Note that the Debian Exim4 packages don’t allow pipes in alias files
by default, so the method described in the section <a class="reference internal" href="#as-a-mail-alias-pipe-process">As a mail alias
pipe process</a> will not work with the default configuration. However,
the method described in this section does. See the discussion in
<tt class="docutils literal"><span class="pre">/usr/share/doc/exim4-config/README.system_aliases</span></tt> on any Debian
system with Exim4 installed.</p>
<p class="last">For more Debian-specific information, see suggested addition to
README.Debian in
<a class="reference external" href="http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283">http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283</a>, which will
hopefully be merged into the Debian package eventually.</p>
</div>
<p>This config makes a few assumptions:</p>
<ul class="simple">
<li>That the mail address corresponding to the tracker instance has the
same name as the directory of the tracker instance, i.e. the mail
interface address corresponding to a Roundup instance called
<tt class="docutils literal"><span class="pre">/var/lib/roundup/trackers/mytracker</span></tt> is <tt class="docutils literal"><span class="pre">mytracker@your.host</span></tt>.</li>
<li>That (at least) all the db subdirectories of all the tracker
instances (ie. <tt class="docutils literal"><span class="pre">/var/lib/roundup/trackers/*/db</span></tt>) are owned by the same
user, in this case, ‘roundup’.</li>
<li>That if the <tt class="docutils literal"><span class="pre">schema.py</span></tt> file exists, then the tracker is ready for
use. Another option is to use the <tt class="docutils literal"><span class="pre">config.ini</span></tt> file (this changed
in 0.8 from <tt class="docutils literal"><span class="pre">config.py</span></tt>).</li>
</ul>
<p>Macros for Roundup router/transport. Should be placed in the macros
section of the Exim4 config:</p>
<div class="highlight-python"><pre># Home dir for your Roundup installation
ROUNDUP_HOME=/var/lib/roundup/trackers
# User and group for Roundup.
ROUNDUP_USER=roundup
ROUNDUP_GROUP=roundup</pre>
</div>
<p>Custom router for Roundup. This will (probably) work if placed at the
beginning of the router section of the Exim4 config:</p>
<div class="highlight-python"><pre>roundup_router:
driver = accept
# The config file config.ini seems like a more natural choice, but the
# file config.py was replaced by config.ini in 0.8, and schema.py needs
# to be present too.
require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
transport = roundup_transport</pre>
</div>
<p>Custom transport for Roundup. This will (probably) work if placed at
the beginning of the router section of the Exim4 config:</p>
<div class="highlight-python"><pre>roundup_transport:
driver = pipe
command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/
current_directory = ROUNDUP_HOME
home_directory = ROUNDUP_HOME
user = ROUNDUP_USER
group = ROUNDUP_GROUP</pre>
</div>
</div>
<div class="section" id="as-a-regular-job-using-a-mailbox-source">
<h4>As a regular job using a mailbox source</h4>
<p>Set <tt class="docutils literal"><span class="pre">roundup-mailgw</span></tt> up to run every 10 minutes or so. For example
(substitute <tt class="docutils literal"><span class="pre">/usr/bin</span></tt> for wherever roundup-mailgw is installed):</p>
<div class="highlight-python"><pre>0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file></pre>
</div>
<p>Where the <tt class="docutils literal"><span class="pre">mail_spool_file</span></tt> argument is the location of the roundup submission
user’s mail spool. On most systems, the spool for a user “issue_tracker”
will be “<tt class="docutils literal"><span class="pre">/var/mail/issue_tracker</span></tt>“.</p>
</div>
<div class="section" id="as-a-regular-job-using-a-pop-source">
<h4>As a regular job using a POP source</h4>
<p>To retrieve from a POP mailbox, use a <em>cron</em> entry similar to the mailbox
one (substitute <tt class="docutils literal"><span class="pre">/usr/bin</span></tt> for wherever roundup-mailgw is
installed):</p>
<div class="highlight-python"><pre>0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec></pre>
</div>
<p>where pop_spec is “<tt class="docutils literal"><span class="pre">username:password@server</span></tt>” that specifies the roundup
submission user’s POP account name, password and server.</p>
<p>On windows, you would set up the command using the windows scheduler.</p>
</div>
<div class="section" id="as-a-regular-job-using-an-imap-source">
<h4>As a regular job using an IMAP source</h4>
<p>To retrieve from an IMAP mailbox, use a <em>cron</em> entry similar to the
POP one (substitute <tt class="docutils literal"><span class="pre">/usr/bin</span></tt> for wherever roundup-mailgw is
installed):</p>
<div class="highlight-python"><pre>0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec></pre>
</div>
<p>where imap_spec is “<tt class="docutils literal"><span class="pre">username:password@server</span></tt>” that specifies the roundup
submission user’s IMAP account name, password and server. You may
optionally include a mailbox to use other than the default <tt class="docutils literal"><span class="pre">INBOX</span></tt> with
“<tt class="docutils literal"><span class="pre">imap</span> <span class="pre">username:password@server</span> <span class="pre">mailbox</span></tt>“.</p>
<p>If you have a secure (ie. HTTPS) IMAP server then you may use <tt class="docutils literal"><span class="pre">imaps</span></tt>
in place of <tt class="docutils literal"><span class="pre">imap</span></tt> in the command to use a secure connection.</p>
<p>As with the POP job, on windows, you would set up the command using the
windows scheduler.</p>
</div>
</div>
<div class="section" id="unix-environment-steps">
<h3>UNIX Environment Steps</h3>
<p>Each tracker ideally should have its own UNIX group, so create
a UNIX group (edit <tt class="docutils literal"><span class="pre">/etc/group</span></tt> or your appropriate NIS map if
you’re using NIS). To continue with my examples so far, I would
create the UNIX group ‘support’, although the name of the UNIX
group does not have to be the same as the tracker name. To this
‘support’ group I then add all of the UNIX usernames who will be
working with this Roundup tracker. In addition to ‘real’ users,
the Roundup email gateway will need to have permissions to this
area as well, so add the user your mail service runs as to the
group (typically “mail” or “daemon”). The UNIX group might then
look like:</p>
<div class="highlight-python"><pre>support:*:1002:jblaine,samh,geezer,mail</pre>
</div>
<p>If you intend to use the web interface (as most people do), you
should also add the username your web server runs as to the group.
My group now looks like this:</p>
<div class="highlight-python"><pre>support:*:1002:jblaine,samh,geezer,mail,apache</pre>
</div>
<p>The tracker “db” directory should be chmod’ed g+sw so that the group can
write to the database, and any new files created in the database will be owned
by the group.</p>
<p>If you’re using the mysql or postgresql backend then you’ll need to ensure
that the tracker user has appropriate permissions to create/modify the
database. If you’re using roundup.cgi, the apache user needs permissions
to modify the database. Alternatively, explicitly specify a database login
in <tt class="docutils literal"><span class="pre">rdbms</span></tt> -> <tt class="docutils literal"><span class="pre">user</span></tt> and <tt class="docutils literal"><span class="pre">password</span></tt> in <tt class="docutils literal"><span class="pre">config.ini</span></tt>.</p>
<p>An alternative to the above is to create a new user who has the sole
responsibility of running roundup. This user:</p>
<ol class="arabic simple">
<li>runs the CGI interface daemon</li>
<li>runs regular polls for email</li>
<li>runs regular checks (using cron) to ensure the daemon is up</li>
<li>optionally has no login password so that nobody but the “root” user
may actually login and play with the roundup setup.</li>
</ol>
<p>If you’re using a Linux system (e.g. Fedora Core) with SELinux enabled,
you will need to ensure that the db directory has a context that
permits the web server to modify and create files. If you’re using the
mysql or postgresql backend you may also need to update your policy to
allow the web server to access the database socket.</p>
</div>
<div class="section" id="additional-language-codecs">
<h3>Additional Language Codecs</h3>
<p>If you intend to send messages to Roundup that use Chinese, Japanese or
Korean encodings the you’ll need to obtain CJKCodecs from
<a class="reference external" href="http://cjkpython.berlios.de/">http://cjkpython.berlios.de/</a></p>
</div>
<div class="section" id="public-tracker-considerations">
<h3>Public Tracker Considerations</h3>
<p>If you run a public tracker, you will eventually have to think about
dealing with spam entered through both the web and mail interfaces.</p>
<p>The <a class="reference external" href="customizing.html">customisation documentation</a> has a simple detector that will block
a lot of spam attempts. Look for the example “Preventing SPAM”.</p>
</div>
</div>
<div class="section" id="maintenance">
<h2><a class="toc-backref" href="#id10">Maintenance</a></h2>
<p>Read the separate <a class="reference external" href="admin_guide.html">administration guide</a> for information about how to
perform common maintenance tasks with Roundup.</p>
</div>
<div class="section" id="upgrading">
<h2><a class="toc-backref" href="#id11">Upgrading</a></h2>
<p>Read the separate <a class="reference external" href="upgrading.html">upgrading document</a>, which describes the steps needed to
upgrade existing tracker trackers for each version of Roundup that is
released.</p>
</div>
<div class="section" id="further-reading">
<h2><a class="toc-backref" href="#id12">Further Reading</a></h2>
<p>If you intend to use Roundup with anything other than the default
templates, if you would like to hack on Roundup, or if you would
like implementation details, you should read <a class="reference external" href="customizing.html">Customising Roundup</a>.</p>
</div>
<div class="section" id="running-multiple-trackers">
<h2><a class="toc-backref" href="#id13">Running Multiple Trackers</a></h2>
<p>Things to think about before you jump off the deep end and install
multiple trackers, which involve additional URLs, user databases, email
addresses, databases to back up, etc.</p>
<ol class="arabic simple">
<li>Do you want a tracker per product you sell/support? You can just add
a new property to your issues called Product, and filter by that. See
the customisation example <a class="reference external" href="customizing.html#adding-a-new-field-to-the-classic-schema">adding a new field to the classic schema</a>.</li>
<li>Do you want to track internal software development issues and customer
support issues separately? You can just set up an additional “issue”
class called “cust_issues” in the same tracker, mimicing the normal
“issue” class, but with different properties. See the customisation
example <a class="reference external" href="customizing.html#tracking-different-types-of-issues">tracking different types of issues</a>.</li>
</ol>
</div>
<div class="section" id="platform-specific-notes">
<h2><a class="toc-backref" href="#id14">Platform-Specific Notes</a></h2>
<div class="section" id="windows-command-line-tools">
<h3>Windows command-line tools</h3>
<p>To make the command-line tools accessible in Windows, you need to update
the “Path” environment variable in the Registry via a dialog box.</p>
<p>On Windows 2000 and later:</p>
<ol class="arabic simple">
<li>Press the “Start” button.</li>
<li>Choose “Settings”</li>
<li>Choose “Control Panel”</li>
<li>Choose “System”</li>
<li>Choose “Advanced”</li>
<li>Choose “Environmental Variables”</li>
<li>Add: “<dir>Scripts” to the “Path” environmental variable.</li>
</ol>
<p>Where <dir> in 7) is the root directory (e.g., <tt class="docutils literal"><span class="pre">C:\Python22\Scripts</span></tt>)
of your Python installation.</p>
<p>I understand that in XP, 2) above is not needed as “Control
Panel” is directly accessible from “Start”.</p>
<p>I do not believe this is possible to do in previous versions of Windows.</p>
</div>
<div class="section" id="windows-server">
<h3>Windows Server</h3>
<p>To have the Roundup web server start up when your machine boots up, there
are two different methods, the scheduler and installing the service.</p>
<div class="section" id="using-the-windows-scheduler">
<h4>1. Using the Windows scheduler</h4>
<p>Set up the following in Scheduled Tasks (note, the following is for a
cygwin setup):</p>
<p><strong>Run</strong></p>
<blockquote>
<tt class="docutils literal"><span class="pre">c:\cygwin\bin\bash.exe</span> <span class="pre">-c</span> <span class="pre">"roundup-server</span> <span class="pre">TheProject=/opt/roundup/trackers/support"</span></tt></blockquote>
<p><strong>Start In</strong></p>
<blockquote>
<tt class="docutils literal"><span class="pre">C:\cygwin\opt\roundup\bin</span></tt></blockquote>
<p><strong>Schedule</strong></p>
<blockquote>
At System Startup</blockquote>
<p>To have the Roundup mail gateway run periodically to poll a POP email address,
set up the following in Scheduled Tasks:</p>
<p><strong>Run</strong></p>
<blockquote>
<tt class="docutils literal"><span class="pre">c:\cygwin\bin\bash.exe</span> <span class="pre">-c</span> <span class="pre">"roundup-mailgw</span> <span class="pre">/opt/roundup/trackers/support</span> <span class="pre">pop</span> <span class="pre">roundup:roundup@mail-server"</span></tt></blockquote>
<p><strong>Start In</strong></p>
<blockquote>
<tt class="docutils literal"><span class="pre">C:\cygwin\opt\roundup\bin</span></tt></blockquote>
<p><strong>Schedule</strong></p>
<blockquote>
<p>Every 10 minutes from 5:00AM for 24 hours every day</p>
<p>Stop the task if it runs for 8 minutes</p>
</blockquote>
</div>
<div class="section" id="installing-the-roundup-server-as-a-windows-service">
<h4>2. Installing the roundup server as a Windows service</h4>
<p>This is more Windows oriented and will make the Roundup server run as
soon as the PC starts up without any need for a login or such. It will
also be available in the normal Windows Administrative Tools.</p>
<p>For this you need first to create a service ini file containing the
relevant settings.</p>
<ol class="arabic">
<li><p class="first">It is created if you execute the following command from within the
scripts directory (notice the use of backslashes):</p>
<div class="highlight-python"><pre>roundup-server -S -C <trackersdir>\server.ini -n <servername> -p 8080 -l <trackersdir>\trackerlog.log software=<trackersdir>\Software</pre>
</div>
<p>where the item <tt class="docutils literal"><span class="pre"><trackersdir></span></tt> is replaced with the physical directory
that hosts all of your trackers. The <tt class="docutils literal"><span class="pre"><servername></span></tt> item is the name
of your roundup server PC, such as w2003srv or similar.</p>
</li>
<li><p class="first">Next open the now created file <tt class="docutils literal"><span class="pre">C:\DATA\roundup\server.ini</span></tt> file
(if your <tt class="docutils literal"><span class="pre"><trackersdir></span></tt> is <tt class="docutils literal"><span class="pre">C:\DATA\roundup</span></tt>).
Check the entries for correctness, especially this one:</p>
<div class="highlight-python"><pre>[trackers]
software = C:\DATA\Roundup\Software</pre>
</div>
<p>(this is an example where the tracker is named software and its home is
<tt class="docutils literal"><span class="pre">C:\DATA\Roundup\Software</span></tt>)</p>
</li>
<li><p class="first">Next give the commands that actually installs and starts the service:</p>
<div class="highlight-python"><pre>roundup-server -C C:\DATA\Roundup\server.ini -c install
roundup-server -c start</pre>
</div>
</li>
<li><p class="first">Finally open the AdministrativeTools/Services applet and locate the
Roundup service entry. Open its properties and change it to start
automatically instead of manually.</p>
</li>
</ol>
<p>If you are using Apache as the webserver you might want to use it with
mod_python instead to serve out Roundup. In that case see the mod_python
instructions above for details.</p>
</div>
</div>
<div class="section" id="sendmail-smrsh">
<h3>Sendmail smrsh</h3>
<p>If you use Sendmail’s <tt class="docutils literal"><span class="pre">smrsh</span></tt> mechanism, you will need to tell
smrsh that roundup-mailgw is a valid/trusted mail handler
before it will work.</p>
<p>This is usually done via the following 2 steps:</p>
<ol class="arabic simple">
<li>make a symlink in <tt class="docutils literal"><span class="pre">/etc/smrsh</span></tt> called <tt class="docutils literal"><span class="pre">roundup-mailgw</span></tt>
which points to the full path of your actual <tt class="docutils literal"><span class="pre">roundup-mailgw</span></tt>
script.</li>
<li>change your alias to <tt class="docutils literal"><span class="pre">"|roundup-mailgw</span> <span class="pre"><tracker_home>"</span></tt></li>
</ol>
</div>
<div class="section" id="linux">
<h3>Linux</h3>
<p>Make sure you read the instructions under <a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a>.</p>
</div>
<div class="section" id="solaris">
<h3>Solaris</h3>
<p>You’ll need to build Python.</p>
<p>Make sure you read the instructions under <a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a>.</p>
</div>
</div>
<div class="section" id="problems-testing-your-python">
<h2><a class="toc-backref" href="#id15">Problems? Testing your Python...</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The <tt class="docutils literal"><span class="pre">run_tests.py</span></tt> script is packaged in Roundup’s source distribution
- users of the Windows installer, other binary distributions or
pre-installed Roundup will need to download the source to use it.</p>
<p class="last">Remember to have a database user ‘rounduptest’ prepared (with
password ‘rounduptest’). This user
must have at least the rights to create and drop databases.
Documentation: details on <a class="reference external" href="http://dev.mysql.com/doc/refman/5.1/en/adding-users.html">adding MySQL users</a>,
for PostgreSQL you want to call the <tt class="docutils literal"><span class="pre">createuser</span></tt> command with the
<tt class="docutils literal"><span class="pre">-d</span></tt> option to allow database creation.</p>
</div>
<p>Once you’ve unpacked roundup’s source, run <tt class="docutils literal"><span class="pre">python</span> <span class="pre">run_tests.py</span></tt> in the
source directory and make sure there are no errors. If there are errors,
please let us know!</p>
<p>If the above fails, you may be using the wrong version of python. Try
<tt class="docutils literal"><span class="pre">python2</span> <span class="pre">run_tests.py</span></tt> or <tt class="docutils literal"><span class="pre">python2.X</span> <span class="pre">run_tests.py</span></tt> where <tt class="docutils literal"><span class="pre">X</span></tt> is in
the set 3,4,5,6 depending on the version(s) of python installed.
If that works, you will need to substitute <tt class="docutils literal"><span class="pre">python2</span></tt> or <tt class="docutils literal"><span class="pre">python2.X</span></tt>
for <tt class="docutils literal"><span class="pre">python</span></tt> in all further commands you use in relation to Roundup –
from installation and scripts.</p>
</div>
</div>
<div class="related related-bottom">
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="upgrading.html" title="Upgrading to newer versions of Roundup"
accesskey="N">next</a></li>
<li class="right" >
<a href="features.html" title="Roundup Features"
accesskey="P">previous</a></li>
<li><a href="index.html">Roundup v1.4 documentation</a></li>
</ul>
</div>
</div>
<div class="footer">
© Copyright 2009, Richard Jones.
<p class="source"><a href="_sources/installation.txt" rel="nofollow">source</a></p>
</div>
</body>
</html>
