"Fossies" - the Fresh Open Source Software Archive

Member "roundup-2.0.0/share/doc/roundup/html/installation.html" (13 Jul 2020, 113801 Bytes) of package /linux/www/roundup-2.0.0.tar.gz:


The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    2   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    3 
    4 <html xmlns="http://www.w3.org/1999/xhtml">
    5   <head>
    6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    7     
    8     <title>Installing Roundup &mdash; Roundup 2.0.0 documentation</title>
    9     
   10     <link rel="stylesheet" href="_static/basic.css" type="text/css" />
   11     <link rel="stylesheet" href="_static/style.css" type="text/css" />
   12     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
   13     <script type="text/javascript">
   14       var DOCUMENTATION_OPTIONS = {
   15           URL_ROOT:    './',
   16           VERSION:     '2.0.0',
   17           COLLAPSE_MODINDEX: false,
   18           FILE_SUFFIX: '.html'
   19       };
   20     </script>
   21     <script type="text/javascript" src="_static/jquery.js"></script>
   22     <script type="text/javascript" src="_static/underscore.js"></script>
   23     <script type="text/javascript" src="_static/doctools.js"></script>
   24     <link rel="index" title="Index" href="genindex.html" />
   25     <link rel="search" title="Search" href="search.html" />
   26     <link rel="top" title="Roundup 2.0.0 documentation" href="index.html" />
   27     <link rel="next" title="Upgrading to newer versions of Roundup" href="upgrading.html" />
   28     <link rel="prev" title="Roundup Features" href="features.html" /> 
   29   </head>
   30   <body>
   31     <div class="header"><h1>Roundup</h1>
   32         <div id="searchbox" style="display: none">
   33           <form class="search" action="search.html" method="get">
   34             <input type="text" name="q" size="18" />
   35             <input type="submit" value="Search" />
   36             <input type="hidden" name="check_keywords" value="yes" />
   37             <input type="hidden" name="area" value="default" />
   38           </form>
   39         </div>
   40         <script type="text/javascript">$('#searchbox').show(0);</script>
   41     </div>
   42     <div class="navigation">
   43       <div class="menu">
   44        
   45     <h3><a href="index.html">Table Of Contents</a></h3>
   46     <ul>
   47 <li><a class="reference internal" href="#">Installing Roundup</a><ul>
   48 <li><a class="reference internal" href="#overview">Overview</a></li>
   49 <li><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
   50 <li><a class="reference internal" href="#optional-components">Optional Components</a></li>
   51 <li><a class="reference internal" href="#getting-roundup">Getting Roundup</a></li>
   52 <li><a class="reference internal" href="#for-the-really-impatient">For The Really Impatient</a></li>
   53 <li><a class="reference internal" href="#installation">Installation</a><ul>
   54 <li><a class="reference internal" href="#basic-installation-steps">Basic Installation Steps</a></li>
   55 <li><a class="reference internal" href="#configuring-your-first-tracker">Configuring your first tracker</a></li>
   56 <li><a class="reference internal" href="#choosing-your-template">Choosing Your Template</a><ul>
   57 <li><a class="reference internal" href="#classic-template">Classic Template</a></li>
   58 <li><a class="reference internal" href="#minimal-template">Minimal Template</a></li>
   59 </ul>
   60 </li>
   61 <li><a class="reference internal" href="#choosing-your-backend">Choosing Your Backend</a></li>
   62 <li><a class="reference internal" href="#configure-a-web-interface">Configure a Web Interface</a><ul>
   63 <li><a class="reference internal" href="#web-server-cgi-bin">Web Server cgi-bin</a></li>
   64 <li><a class="reference internal" href="#cgi-bin-for-limited-access-hosting">CGI-bin for Limited-Access Hosting</a></li>
   65 <li><a class="reference internal" href="#stand-alone-web-server">Stand-alone Web Server</a></li>
   66 <li><a class="reference internal" href="#zope-product-zroundup">Zope Product - ZRoundup</a></li>
   67 <li><a class="reference internal" href="#apache-http-server-with-mod-wsgi">Apache HTTP Server with mod_wsgi</a><ul>
   68 <li><a class="reference internal" href="#background">Background</a></li>
   69 <li><a class="reference internal" href="#install-mod-wsgi">Install mod-wsgi</a><ul>
   70 <li><a class="reference internal" href="#pip-install-of-mod-wsgi">Pip install of mod_wsgi</a></li>
   71 <li><a class="reference internal" href="#package-manager-install-of-mod-wsgi">Package manager install of mod_wsgi</a></li>
   72 </ul>
   73 </li>
   74 <li><a class="reference internal" href="#configure-web-interface-via-wsgi-handler">Configure web interface via wsgi_handler</a></li>
   75 <li><a class="reference internal" href="#to-run-the-tracker-on-port-8000-as-a-foreground-process">To run the tracker on Port 8000 as a foreground process</a></li>
   76 <li><a class="reference internal" href="#run-tracker-as-background-daemon">Run tracker as background daemon</a></li>
   77 <li><a class="reference internal" href="#to-run-mod-wsgi-on-port-80">To run mod_wsgi on PORT 80</a><ul>
   78 <li><a class="reference internal" href="#to-run-as-a-foreground-process">To run as a foreground process</a></li>
   79 <li><a class="reference internal" href="#to-run-as-a-background-process">To run as a background process</a></li>
   80 </ul>
   81 </li>
   82 </ul>
   83 </li>
   84 <li><a class="reference internal" href="#apache-http-server-with-mod-python">Apache HTTP Server with mod_python</a></li>
   85 <li><a class="reference internal" href="#wsgi-variations">WSGI Variations</a><ul>
   86 <li><a class="reference internal" href="#apache-alternate">Apache Alternate</a></li>
   87 <li><a class="reference internal" href="#gunicorn-installation">Gunicorn Installation</a></li>
   88 <li><a class="reference internal" href="#uwsgi-installation">uWSGI Installation</a></li>
   89 </ul>
   90 </li>
   91 </ul>
   92 </li>
   93 <li><a class="reference internal" href="#configure-an-email-interface">Configure an Email Interface</a><ul>
   94 <li><a class="reference internal" href="#as-a-mail-alias-pipe-process">As a mail alias pipe process</a></li>
   95 <li><a class="reference internal" 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>
   96 <li><a class="reference internal" href="#as-a-regular-job-using-a-mailbox-source">As a regular job using a mailbox source</a></li>
   97 <li><a class="reference internal" href="#as-a-regular-job-using-a-pop-source">As a regular job using a POP source</a></li>
   98 <li><a class="reference internal" href="#as-a-regular-job-using-an-imap-source">As a regular job using an IMAP source</a></li>
   99 </ul>
  100 </li>
  101 <li><a class="reference internal" href="#unix-environment-steps">UNIX Environment Steps</a></li>
  102 <li><a class="reference internal" href="#public-tracker-considerations">Public Tracker Considerations</a></li>
  103 </ul>
  104 </li>
  105 <li><a class="reference internal" href="#maintenance">Maintenance</a></li>
  106 <li><a class="reference internal" href="#upgrading">Upgrading</a></li>
  107 <li><a class="reference internal" href="#further-reading">Further Reading</a></li>
  108 <li><a class="reference internal" href="#running-multiple-trackers">Running Multiple Trackers</a></li>
  109 <li><a class="reference internal" href="#platform-specific-notes">Platform-Specific Notes</a><ul>
  110 <li><a class="reference internal" href="#windows-command-line-tools">Windows command-line tools</a></li>
  111 <li><a class="reference internal" href="#windows-server">Windows Server</a><ul>
  112 <li><a class="reference internal" href="#using-the-windows-scheduler">1. Using the Windows scheduler</a></li>
  113 <li><a class="reference internal" href="#installing-the-roundup-server-as-a-windows-service">2. Installing the roundup server as a Windows service</a></li>
  114 </ul>
  115 </li>
  116 <li><a class="reference internal" href="#sendmail-smrsh">Sendmail smrsh</a></li>
  117 <li><a class="reference internal" href="#linux">Linux</a></li>
  118 <li><a class="reference internal" href="#solaris">Solaris</a></li>
  119 </ul>
  120 </li>
  121 <li><a class="reference internal" href="#problems-testing-your-python">Problems? Testing your Python…</a></li>
  122 </ul>
  123 </li>
  124 </ul>
  125 
  126     <h4>Previous topic</h4>
  127     <p class="topless"><a href="features.html"
  128                           title="previous chapter">Roundup Features</a></p>
  129     <h4>Next topic</h4>
  130     <p class="topless"><a href="upgrading.html"
  131                           title="next chapter">Upgrading to newer versions of Roundup</a></p>
  132     <h3>This Page</h3>
  133     <ul class="this-page-menu">
  134       <li><a href="_sources/installation.txt"
  135              rel="nofollow">Show Source</a></li>
  136     </ul>
  137   <div id="searchbox" style="display: none">
  138     <h3>Quick search</h3>
  139       <form class="search" action="search.html" method="get">
  140         <input type="text" name="q" size="18" />
  141         <input type="submit" value="Go" />
  142         <input type="hidden" name="check_keywords" value="yes" />
  143         <input type="hidden" name="area" value="default" />
  144       </form>
  145       <p style="font-size: 90%">Enter search terms or a module, class or function name.</p>
  146   </div>
  147   <script type="text/javascript">$('#searchbox').show(0);</script>
  148       </div>
  149     </div>
  150     <div class="content">
  151        
  152     <div class="related related-top">
  153       <ul>
  154         <li class="right" style="margin-right: 10px">
  155           <a href="genindex.html" title="General Index"
  156              accesskey="I">index</a></li>
  157         <li class="right" >
  158           <a href="upgrading.html" title="Upgrading to newer versions of Roundup"
  159              accesskey="N">next</a></li>
  160         <li class="right" >
  161           <a href="features.html" title="Roundup Features"
  162              accesskey="P">previous</a></li>
  163         <li><a href="index.html">Roundup 2.0.0 documentation</a></li> 
  164       </ul>
  165     </div>
  166        
  167   <div class="section" id="installing-roundup">
  168 <span id="index-0"></span><h1>Installing Roundup<a class="headerlink" href="#installing-roundup" title="Permalink to this headline"></a></h1>
  169 <div class="contents local topic" id="contents">
  170 <ul class="simple">
  171 <li><a class="reference internal" href="#overview" id="id3">Overview</a></li>
  172 <li><a class="reference internal" href="#prerequisites" id="id4">Prerequisites</a></li>
  173 <li><a class="reference internal" href="#optional-components" id="id5">Optional Components</a></li>
  174 <li><a class="reference internal" href="#getting-roundup" id="id6">Getting Roundup</a></li>
  175 <li><a class="reference internal" href="#for-the-really-impatient" id="id7">For The Really Impatient</a></li>
  176 <li><a class="reference internal" href="#installation" id="id8">Installation</a><ul>
  177 <li><a class="reference internal" href="#basic-installation-steps" id="id9">Basic Installation Steps</a></li>
  178 <li><a class="reference internal" href="#configuring-your-first-tracker" id="id10">Configuring your first tracker</a></li>
  179 <li><a class="reference internal" href="#choosing-your-template" id="id11">Choosing Your Template</a></li>
  180 <li><a class="reference internal" href="#choosing-your-backend" id="id12">Choosing Your Backend</a></li>
  181 <li><a class="reference internal" href="#configure-a-web-interface" id="id13">Configure a Web Interface</a></li>
  182 <li><a class="reference internal" href="#configure-an-email-interface" id="id14">Configure an Email Interface</a></li>
  183 <li><a class="reference internal" href="#unix-environment-steps" id="id15">UNIX Environment Steps</a></li>
  184 <li><a class="reference internal" href="#public-tracker-considerations" id="id16">Public Tracker Considerations</a></li>
  185 </ul>
  186 </li>
  187 <li><a class="reference internal" href="#maintenance" id="id17">Maintenance</a></li>
  188 <li><a class="reference internal" href="#upgrading" id="id18">Upgrading</a></li>
  189 <li><a class="reference internal" href="#further-reading" id="id19">Further Reading</a></li>
  190 <li><a class="reference internal" href="#running-multiple-trackers" id="id20">Running Multiple Trackers</a></li>
  191 <li><a class="reference internal" href="#platform-specific-notes" id="id21">Platform-Specific Notes</a><ul>
  192 <li><a class="reference internal" href="#windows-command-line-tools" id="id22">Windows command-line tools</a></li>
  193 <li><a class="reference internal" href="#windows-server" id="id23">Windows Server</a></li>
  194 <li><a class="reference internal" href="#sendmail-smrsh" id="id24">Sendmail smrsh</a></li>
  195 <li><a class="reference internal" href="#linux" id="id25">Linux</a></li>
  196 <li><a class="reference internal" href="#solaris" id="id26">Solaris</a></li>
  197 </ul>
  198 </li>
  199 <li><a class="reference internal" href="#problems-testing-your-python" id="id27">Problems? Testing your Python…</a></li>
  200 </ul>
  201 </div>
  202 <div class="section" id="overview">
  203 <h2><a class="toc-backref" href="#id3">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline"></a></h2>
  204 <p>Broken out separately, there are several conceptual pieces to a
  205 Roundup installation:</p>
  206 <dl class="docutils">
  207 <dt>Roundup trackers</dt>
  208 <dd>Trackers consist of issues (be they bug reports or otherwise), tracker
  209 configuration file(s), web HTML files etc. Roundup trackers are initialised
  210 with a “Template” which defines the fields usable/assignable on a
  211 per-issue basis.  Descriptions of the provided templates are given in
  212 <a class="reference internal" href="#choosing-your-template">choosing your template</a>.</dd>
  213 <dt>Roundup support code</dt>
  214 <dd>Installed into your Python install’s lib directory.</dd>
  215 <dt>Roundup scripts</dt>
  216 <dd>These include the email gateway, the roundup
  217 HTTP server, the roundup administration command-line interface, etc.</dd>
  218 </dl>
  219 </div>
  220 <div class="section" id="prerequisites">
  221 <h2><a class="toc-backref" href="#id4">Prerequisites</a><a class="headerlink" href="#prerequisites" title="Permalink to this headline"></a></h2>
  222 <p>Roundup requires Python 2.7 or 3.4 or newer with a functioning
  223 anydbm module. Download the latest version from <a class="reference external" href="https://www.python.org/">https://www.python.org/</a>.
  224 It is highly recommended that users install the latest patch version
  225 of python as these contain many fixes to serious bugs.</p>
  226 <p>Some variants of Linux will need an additional “python dev” package
  227 installed for Roundup installation to work. Debian and derivatives, are
  228 known to require this.</p>
  229 <p>If you are using the Roundup Windows installer on a 64 bit system and
  230 you get the error message:</p>
  231 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="s2">&quot;No Python installation found in the registry&quot;</span>
  232 </pre></div>
  233 </div>
  234 <p>you need to install a 32 bit version of python. The 64 bit versions
  235 use a different registry key that the installer doesn’t detect. See:
  236 <a class="reference external" href="https://issues.roundup-tracker.org/issue2550718">https://issues.roundup-tracker.org/issue2550718</a> for details.</p>
  237 </div>
  238 <div class="section" id="optional-components">
  239 <h2><a class="toc-backref" href="#id5">Optional Components</a><a class="headerlink" href="#optional-components" title="Permalink to this headline"></a></h2>
  240 <p>You may optionally install and use:</p>
  241 <dl class="docutils">
  242 <dt>Timezone Definitions</dt>
  243 <dd>Full timezone support requires <a class="reference external" href="https://pypi.org/project/pytz/">pytz</a> module (version 2005i or later)
  244 which brings the <a class="reference external" href="https://www.iana.org/time-zones">Olson tz database</a> into Python.  If <a class="reference external" href="https://pypi.org/project/pytz/">pytz</a> is not
  245 installed, timezones may be specified as numeric hour offsets only.
  246 This is optional but strongly suggested.</dd>
  247 <dt>An RDBMS</dt>
  248 <dd>Sqlite, MySQL and Postgresql are all supported by Roundup and will be
  249 used if available. One of these is recommended if you are anticipating a
  250 large user base (see <a class="reference internal" href="#choosing-your-backend">choosing your backend</a> below).</dd>
  251 </dl>
  252 <dl class="docutils" id="index-1">
  253 <dt>Xapian full-text indexer</dt>
  254 <dd><p class="first">The <a class="reference external" href="https://xapian.org/">Xapian</a> full-text indexer is also supported and will be used by
  255 default if it is available. This is strongly recommended if you are
  256 anticipating a large number of issues (&gt; 5000).</p>
  257 <p>You may install Xapian at any time, even after a tracker has been
  258 installed and used. You will need to run the “roundup-admin reindex”
  259 command if the tracker has existing data.</p>
  260 <p>Roundup requires Xapian 1.0.0 or newer.</p>
  261 <p class="last">Note that capitalization is not preserved by the Xapian search.
  262 This is required to make the porter stemmer work so that searching
  263 for silent also returns documents with the word silently. Note that
  264 the current stemming implementation is designed for English.</p>
  265 </dd>
  266 <dt>Whoosh full-text indexer</dt>
  267 <dd><p class="first">The <a class="reference external" href="https://bitbucket.org/mchaput/whoosh/wiki/Home">Whoosh</a> full-text indexer is also supported and will be used by
  268 default if it is available (and Xapian is not installed). This is
  269 recommended if you are anticipating a large number of issues (&gt; 5000).</p>
  270 <p>You may install Whoosh at any time, even after a tracker has been
  271 installed and used. You will need to run the “roundup-admin reindex”
  272 command if the tracker has existing data.</p>
  273 <p class="last">Roundup was tested with Whoosh 2.5.7, but earlier versions in the
  274 2.0 series may work. Whoosh is a pure python indexer so it is slower
  275 than Xapian, but should be useful for moderately sized trackers.
  276 It uses the StandardAnalyzer which is suited for Western languages.</p>
  277 </dd>
  278 <dt>pyopenssl</dt>
  279 <dd>If <a class="reference external" href="http://pyopenssl.sourceforge.net">pyopenssl</a> is installed the roundup-server can be configured
  280 to serve trackers over SSL. If you are going to serve roundup via
  281 proxy through a server with SSL support (e.g. apache) then this is
  282 unnecessary.</dd>
  283 <dt>gpg</dt>
  284 <dd>If <a class="reference external" href="https://www.gnupg.org/software/gpgme/index.html">gpg</a> is installed you can configure the mail gateway to perform
  285 verification or decryption of incoming OpenPGP MIME messages. When
  286 configured, you can require email to be cryptographically signed
  287 before roundup will allow it to make modifications to issues.</dd>
  288 <dt>jinja2</dt>
  289 <dd>To use the jinja2 template (may still be experimental, check out
  290 its TEMPLATE-INFO.txt file) you need
  291 to have the <a class="reference external" href="http://jinja.pocoo.org/">jinja2</a> template engine installed.</dd>
  292 <dt>pyjwt</dt>
  293 <dd>To use jwt tokens for login (experimental), install pyjwt. If you
  294 don’t have it installed, jwt tokens are not supported.</dd>
  295 <dt>docutils</dt>
  296 <dd>To use ReStructuredText rendering you need to have the docutils
  297 package installed.</dd>
  298 <dt>markdown, markdown2 or mistune</dt>
  299 <dd>To use markdown rendering you need to have the markdown, markdown2
  300 or mistune package installed.</dd>
  301 <dt>Windows Service</dt>
  302 <dd>You can run Roundup as a Windows service if <a class="reference external" href="https://pypi.org/project/pywin32/">pywin32</a> is installed.
  303 Otherwise it must be started manually.</dd>
  304 </dl>
  305 </div>
  306 <div class="section" id="getting-roundup">
  307 <h2><a class="toc-backref" href="#id6">Getting Roundup</a><a class="headerlink" href="#getting-roundup" title="Permalink to this headline"></a></h2>
  308 <div class="admonition note">
  309 <p class="first admonition-title">Note</p>
  310 <p class="last">Some systems, such as Debian and NetBSD, already have Roundup
  311 installed. Try running the command “roundup-admin” with no arguments,
  312 and if it runs you may skip the <a class="reference internal" href="#basic-installation-steps">Basic Installation Steps</a>
  313 below and go straight to <a class="reference internal" href="#configuring-your-first-tracker">configuring your first tracker</a>.</p>
  314 </div>
  315 <p>Download the latest version from <a class="reference external" href="http://www.roundup-tracker.org/">http://www.roundup-tracker.org/</a>.</p>
  316 </div>
  317 <div class="section" id="for-the-really-impatient">
  318 <h2><a class="toc-backref" href="#id7">For The Really Impatient</a><a class="headerlink" href="#for-the-really-impatient" title="Permalink to this headline"></a></h2>
  319 <p>If you just want to give Roundup a whirl Right Now, then simply unpack
  320 and run <code class="docutils literal"><span class="pre">demo.py</span></code> (it will be available as <code class="docutils literal"><span class="pre">roundup-demo</span></code> script
  321 after installation).</p>
  322 <p>This will set up a simple demo tracker on your machine. <a class="footnote-reference" href="#id2" id="id1">[1]</a>
  323 When it’s done, it’ll print out a URL to point your web browser at
  324 so you may start playing. Three users will be set up:</p>
  325 <ol class="arabic simple">
  326 <li>anonymous - the “default” user with permission to do very little</li>
  327 <li>demo (password “demo”) - a normal user who may create issues</li>
  328 <li>admin (password “admin”) - an administrative user who has complete
  329 access to the tracker</li>
  330 </ol>
  331 <table class="docutils footnote" frame="void" id="id2" rules="none">
  332 <colgroup><col class="label" /><col /></colgroup>
  333 <tbody valign="top">
  334 <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.
  335 If you run demo on a server host, please stop the demo when
  336 it has shown startup notice, open file <code class="docutils literal"><span class="pre">demo/config.ini</span></code> with
  337 your editor, change host name in the <code class="docutils literal"><span class="pre">web</span></code> option in section
  338 <code class="docutils literal"><span class="pre">[tracker]</span></code>, save the file, then re-run the demo program.</td></tr>
  339 </tbody>
  340 </table>
  341 </div>
  342 <div class="section" id="installation">
  343 <h2><a class="toc-backref" href="#id8">Installation</a><a class="headerlink" href="#installation" title="Permalink to this headline"></a></h2>
  344 <p>Set aside 15-30 minutes. There’s several steps to follow in your
  345 installation:</p>
  346 <ol class="arabic simple">
  347 <li><a class="reference internal" href="#basic-installation-steps">basic installation steps</a> if Roundup is not installed on your system</li>
  348 <li><a class="reference internal" href="#configuring-your-first-tracker">configuring your first tracker</a> that all installers must follow</li>
  349 <li>then optionally <a class="reference internal" href="#configure-a-web-interface">configure a web interface</a></li>
  350 <li>and optionally <a class="reference internal" href="#configure-an-email-interface">configure an email interface</a></li>
  351 <li><a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a> to take if you’re installing on a shared
  352 UNIX machine and want to restrict local access to roundup</li>
  353 </ol>
  354 <p>For information about how Roundup installs, see the <a class="reference external" href="admin_guide.html">administration
  355 guide</a>.</p>
  356 <p>The following assumes that you are using the source distribution.  If
  357 you are using the Windows installer, run it with Administrator
  358 privileges so it can correctly update the registry.</p>
  359 <div class="section" id="basic-installation-steps">
  360 <h3><a class="toc-backref" href="#id9">Basic Installation Steps</a><a class="headerlink" href="#basic-installation-steps" title="Permalink to this headline"></a></h3>
  361 <p>To install the Roundup support code into your Python tree and
  362 Roundup scripts into /usr/bin (substitute that path for whatever is
  363 appropriate on your system). You need to have write permissions
  364 for these locations, eg. being root on unix:</p>
  365 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span>
  366 </pre></div>
  367 </div>
  368 <p>If you would like to place the Roundup scripts in a directory other
  369 than <code class="docutils literal"><span class="pre">/usr/bin</span></code>, then specify the preferred location with
  370 <code class="docutils literal"><span class="pre">--install-scripts</span></code>. For example, to install them in
  371 <code class="docutils literal"><span class="pre">/opt/roundup/bin</span></code>:</p>
  372 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span> <span class="o">--</span><span class="n">install</span><span class="o">-</span><span class="n">scripts</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="nb">bin</span>
  373 </pre></div>
  374 </div>
  375 <p>You can also use the <code class="docutils literal"><span class="pre">--prefix</span></code> option to use a completely different
  376 base directory, if you do not want to use administrator rights. If you
  377 choose to do this, you may have to change Python’s search path (sys.path)
  378 yourself.</p>
  379 </div>
  380 <div class="section" id="configuring-your-first-tracker">
  381 <h3><a class="toc-backref" href="#id10">Configuring your first tracker</a><a class="headerlink" href="#configuring-your-first-tracker" title="Permalink to this headline"></a></h3>
  382 <ol class="arabic">
  383 <li><p class="first">To create a Roundup tracker (necessary to do before you can
  384 use the software in any real fashion), you need to set up a “tracker
  385 home”:</p>
  386 <ol class="loweralpha">
  387 <li><p class="first">(Optional) If you intend to keep your roundup trackers
  388 under one top level directory which does not exist yet,
  389 you should create that directory now.  Example:</p>
  390 <div class="highlight-default"><div class="highlight"><pre><span></span><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>
  391 </pre></div>
  392 </div>
  393 </li>
  394 <li><p class="first">Either add the Roundup script location to your <code class="docutils literal"><span class="pre">PATH</span></code>
  395 environment variable or specify the full path to
  396 the command in the next step.</p>
  397 </li>
  398 </ol>
  399 <ol class="loweralpha" id="index-2" start="3">
  400 <li><p class="first">Install a new tracker with the command <code class="docutils literal"><span class="pre">roundup-admin</span> <span class="pre">install</span></code>.
  401 You will be asked a series of questions.  Descriptions of the provided
  402 templates can be found in <a class="reference internal" href="#choosing-your-template">choosing your template</a> below.  Descriptions
  403 of the available backends can be found in <a class="reference internal" href="#choosing-your-backend">choosing your backend</a>
  404 below.  The questions will be something like (you may have more
  405 templates or backends available):</p>
  406 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Enter</span> <span class="n">tracker</span> <span class="n">home</span><span class="p">:</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><span class="o">/</span><span class="n">support</span>
  407 <span class="n">Templates</span><span class="p">:</span> <span class="n">classic</span>
  408 <span class="n">Select</span> <span class="n">template</span> <span class="p">[</span><span class="n">classic</span><span class="p">]:</span> <span class="n">classic</span>
  409 <span class="n">Back</span> <span class="n">ends</span><span class="p">:</span> <span class="n">anydbm</span><span class="p">,</span> <span class="n">mysql</span><span class="p">,</span> <span class="n">sqlite</span>
  410 <span class="n">Select</span> <span class="n">backend</span> <span class="p">[</span><span class="n">anydbm</span><span class="p">]:</span> <span class="n">anydbm</span>
  411 </pre></div>
  412 </div>
  413 <p>Note: “Back ends” selection list depends on availability of
  414 third-party database modules.  Standard python distribution
  415 includes anydbm module only.</p>
  416 <p>The “support” part of the tracker name can be anything you want - it
  417 is going to be used as the directory that the tracker information
  418 will be stored in.</p>
  419 <p>You will now be directed to edit the tracker configuration and
  420 initial schema.  At a minimum, you must set “main :: admin_email”
  421 (that’s the “admin_email” option in the “main” section) “mail ::
  422 host”, “tracker :: web” and “mail :: domain”.  If you get stuck,
  423 and get configuration file errors, then see the <a class="reference external" href="customizing.html#tracker-configuration">tracker
  424 configuration</a> section of the <a class="reference external" href="customizing.html">customisation documentation</a>.</p>
  425 <p>If you just want to get set up to test things quickly (and follow
  426 the instructions in step 3 below), you can even just set the
  427 “tracker :: web” variable to:</p>
  428 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">web</span> <span class="o">=</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span><span class="mi">8080</span><span class="o">/</span><span class="n">support</span><span class="o">/</span>
  429 </pre></div>
  430 </div>
  431 <p>The URL <em>must</em> end in a ‘/’, or your web interface <em>will not work</em>.
  432 See <a class="reference external" href="customizing.html">Customising Roundup</a> for details on configuration and schema
  433 changes. You may change any of the configuration after
  434 you’ve initialised the tracker - it’s just better to have valid values
  435 for this stuff now.</p>
  436 </li>
  437 </ol>
  438 <ol class="loweralpha" id="index-3" start="4">
  439 <li><p class="first">Initialise the tracker database with <code class="docutils literal"><span class="pre">roundup-admin</span> <span class="pre">initialise</span></code>.
  440 You will need to supply an admin password at this step. You will be
  441 prompted:</p>
  442 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Admin</span> <span class="n">Password</span><span class="p">:</span>
  443        <span class="n">Confirm</span><span class="p">:</span>
  444 </pre></div>
  445 </div>
  446 <p>Note: running this command will <em>destroy any existing data in the
  447 database</em>. In the case of MySQL and PostgreSQL, any existing database
  448 will be dropped and re-created.</p>
  449 <p>Once this is done, the tracker has been created. See the note in
  450 the user_guide on how to initialise a tracker without being
  451 prompted for the password or exposing the password on the command
  452 line.</p>
  453 </li>
  454 </ol>
  455 </li>
  456 <li><p class="first">At this point, your tracker is set up, but doesn’t have a nice user
  457 interface. To set that up, we need to <a class="reference internal" href="#configure-a-web-interface">configure a web interface</a> and
  458 optionally <a class="reference internal" href="#configure-an-email-interface">configure an email interface</a>. If you want to try your
  459 new tracker out, assuming “tracker :: web” is set to
  460 <code class="docutils literal"><span class="pre">'http://localhost:8080/support/'</span></code>, run:</p>
  461 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">roundup</span><span class="o">-</span><span class="n">server</span> <span class="n">support</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><span class="o">/</span><span class="n">support</span>
  462 </pre></div>
  463 </div>
  464 <p>then direct your web browser at:</p>
  465 <blockquote>
  466 <div><p><a class="reference external" href="http://localhost:8080/support/">http://localhost:8080/support/</a></p>
  467 </div></blockquote>
  468 <p>and you should see the tracker interface.</p>
  469 <p>To run your tracker on some interface other than 127.0.0.1 and port
  470 8080 (make sure you change the “tracker :: web” changes to match) use:</p>
  471 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">roundup</span><span class="o">-</span><span class="n">server</span> <span class="o">-</span><span class="n">p</span> <span class="mi">1080</span> <span class="o">-</span><span class="n">n</span> <span class="mf">0.0</span><span class="o">.</span><span class="mf">0.0</span> <span class="n">support</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><span class="o">/</span><span class="n">support</span>
  472 </pre></div>
  473 </div>
  474 <p>to run the server at port 1080 and bind to all ip addresses on your system.
  475 Then direct your web browser to <code class="docutils literal"><span class="pre">http://your_host_name:1080/support</span></code>.</p>
  476 </li>
  477 </ol>
  478 </div>
  479 <div class="section" id="choosing-your-template">
  480 <h3><a class="toc-backref" href="#id11">Choosing Your Template</a><a class="headerlink" href="#choosing-your-template" title="Permalink to this headline"></a></h3>
  481 <div class="section" id="classic-template">
  482 <h4>Classic Template<a class="headerlink" href="#classic-template" title="Permalink to this headline"></a></h4>
  483 <p>The classic template is the one defined in the <a class="reference external" href="spec.html">Roundup Specification</a>. It
  484 holds issues which have priorities and statuses. Each issue may also have a
  485 set of messages which are disseminated to the issue’s list of nosy users.</p>
  486 </div>
  487 <div class="section" id="minimal-template">
  488 <h4>Minimal Template<a class="headerlink" href="#minimal-template" title="Permalink to this headline"></a></h4>
  489 <p>The minimal template has the minimum setup required for a tracker
  490 installation. That is, it has the configuration files, defines a user database
  491 and the basic HTML interface to that. It’s a completely clean slate for you to
  492 create your tracker on.</p>
  493 </div>
  494 </div>
  495 <div class="section" id="choosing-your-backend">
  496 <span id="index-4"></span><h3><a class="toc-backref" href="#id12">Choosing Your Backend</a><a class="headerlink" href="#choosing-your-backend" title="Permalink to this headline"></a></h3>
  497 <p>The actual storage of Roundup tracker information is handled by backends.
  498 There’s several to choose from, each with benefits and limitations:</p>
  499 <table border="1" class="docutils">
  500 <colgroup>
  501 <col width="18%" />
  502 <col width="20%" />
  503 <col width="9%" />
  504 <col width="54%" />
  505 </colgroup>
  506 <thead valign="bottom">
  507 <tr class="row-odd"><th class="head">Name</th>
  508 <th class="head">Speed</th>
  509 <th class="head">Users</th>
  510 <th class="head">Support</th>
  511 </tr>
  512 </thead>
  513 <tbody valign="top">
  514 <tr class="row-even"><td>anydbm</td>
  515 <td>Slowest</td>
  516 <td>Few</td>
  517 <td>Always available</td>
  518 </tr>
  519 <tr class="row-odd"><td>sqlite</td>
  520 <td>Fastest(*)</td>
  521 <td>Few</td>
  522 <td>May need install (<a class="reference external" href="https://pysqlite.org/">PySQLite</a>)</td>
  523 </tr>
  524 <tr class="row-even"><td>postgresql</td>
  525 <td>Fast</td>
  526 <td>Many</td>
  527 <td>Needs install/admin (<a class="reference external" href="http://initd.org/psycopg/">psycopg</a>)</td>
  528 </tr>
  529 <tr class="row-odd"><td>mysql</td>
  530 <td>Fast</td>
  531 <td>Many</td>
  532 <td>Needs install/admin (<a class="reference external" href="https://pypi.org/project/mysqlclient/">MySQLdb</a>)</td>
  533 </tr>
  534 </tbody>
  535 </table>
  536 <dl class="docutils">
  537 <dt><strong>sqlite</strong></dt>
  538 <dd><p class="first">This uses the embedded database engine <a class="reference external" href="https://pysqlite.org/">PySQLite</a> to provide a very fast
  539 backend. This is not suitable for trackers which will have many
  540 simultaneous users, but requires much less installation and maintenance
  541 effort than more scalable postgresql and mysql backends.</p>
  542 <p>SQLite is supported via PySQLite versions 1.1.7, 2.1.0 and sqlite3 (the last
  543 being bundled with Python 2.5+)</p>
  544 <p class="last">Installed SQLite should be the latest version available (3.3.8 is known
  545 to work, 3.1.3 is known to have problems).</p>
  546 </dd>
  547 <dt><strong>postgresql</strong></dt>
  548 <dd>Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for
  549 additional installation steps and requirements. You must also configure
  550 the <code class="docutils literal"><span class="pre">rdbms</span></code> section of your tracker’s <code class="docutils literal"><span class="pre">config.ini</span></code>.  It is recommended
  551 that you use at least version 1.1.21 of psycopg.</dd>
  552 <dt><strong>mysql</strong></dt>
  553 <dd>Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
  554 installation steps and requirements. You must also configure the <code class="docutils literal"><span class="pre">rdbms</span></code>
  555 section of your tracker’s <code class="docutils literal"><span class="pre">config.ini</span></code></dd>
  556 </dl>
  557 <p>You may defer your decision by setting your tracker up with the anydbm
  558 backend (which is guaranteed to be available) and switching to one of the
  559 other backends at any time using the instructions in the <a class="reference external" href="admin_guide.html">administration
  560 guide</a>.</p>
  561 <p>Regardless of which backend you choose, Roundup will attempt to initialise
  562 a new database for you when you run the “<code class="docutils literal"><span class="pre">roundup-admin</span> <span class="pre">initialise</span></code>” command.
  563 In the case of MySQL and PostgreSQL you will need to have the appropriate
  564 privileges to create databases.</p>
  565 </div>
  566 <div class="section" id="configure-a-web-interface">
  567 <h3><a class="toc-backref" href="#id13">Configure a Web Interface</a><a class="headerlink" href="#configure-a-web-interface" title="Permalink to this headline"></a></h3>
  568 <p>There are multiple web interfaces to choose from:</p>
  569 <ol class="arabic simple">
  570 <li><a class="reference internal" href="#web-server-cgi-bin">web server cgi-bin</a></li>
  571 <li><a class="reference internal" href="#cgi-bin-for-limited-access-hosting">cgi-bin for limited-access hosting</a></li>
  572 <li><a class="reference internal" href="#stand-alone-web-server">stand-alone web server</a></li>
  573 <li><a class="reference internal" href="#zope-product-zroundup">Zope product - ZRoundup</a></li>
  574 <li><a class="reference internal" href="#apache-http-server-with-mod-wsgi">Apache HTTP Server with mod_wsgi</a></li>
  575 <li><a class="reference internal" href="#apache-http-server-with-mod-python">Apache HTTP Server with mod_python</a>  (deprecated)</li>
  576 <li><a class="reference internal" href="#wsgi-variations">WSGI Variations</a></li>
  577 </ol>
  578 <p>You may need to give the web server user permission to access the tracker home
  579 - see the <a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a> for information. You may also need to
  580 configure your system in some way - see <a class="reference internal" href="#platform-specific-notes">platform-specific notes</a>.</p>
  581 <div class="section" id="web-server-cgi-bin">
  582 <span id="index-5"></span><h4>Web Server cgi-bin<a class="headerlink" href="#web-server-cgi-bin" title="Permalink to this headline"></a></h4>
  583 <p>A benefit of using the cgi-bin approach is that it’s the easiest way to
  584 restrict access to your tracker to only use HTTPS. Access will be slower
  585 than through the <a class="reference internal" href="#stand-alone-web-server">stand-alone web server</a> though.</p>
  586 <p>If your Python isn’t installed as “python” then you’ll need to edit
  587 the <code class="docutils literal"><span class="pre">roundup.cgi</span></code> script to fix the first line.</p>
  588 <p>If you’re using IIS on a Windows platform, you’ll need to run this command
  589 for the cgi to work (it turns on the PATH_INFO cgi variable):</p>
  590 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">adsutil</span><span class="o">.</span><span class="n">vbs</span> <span class="nb">set</span> <span class="n">w3svc</span><span class="o">/</span><span class="n">AllowPathInfoForScriptMappings</span> <span class="n">TRUE</span>
  591 </pre></div>
  592 </div>
  593 <p>The <code class="docutils literal"><span class="pre">adsutil.vbs</span></code> file can be found in either <code class="docutils literal"><span class="pre">c:\inetpub\adminscripts</span></code>
  594 or <code class="docutils literal"><span class="pre">c:\winnt\system32\inetsrv\adminsamples\</span></code> or
  595 <code class="docutils literal"><span class="pre">c:\winnt\system32\inetsrv\adminscripts\</span></code> depending on your installation.</p>
  596 <p>More information about ISS setup may be found at:</p>
  597 <blockquote>
  598 <div><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></div></blockquote>
  599 <p>Copy the <code class="docutils literal"><span class="pre">frontends/roundup.cgi</span></code> file to your web server’s <code class="docutils literal"><span class="pre">cgi-bin</span></code>
  600 directory. You will need to configure it to tell it where your tracker home
  601 is. You can do this either:</p>
  602 <dl class="docutils">
  603 <dt>Through an environment variable</dt>
  604 <dd>Set the variable TRACKER_HOMES to be a colon (“:”) separated list of
  605 name=home pairs (if you’re using apache, the SetEnv directive can do this)</dd>
  606 <dt>Directly in the <code class="docutils literal"><span class="pre">roundup.cgi</span></code> file itself</dt>
  607 <dd>Add your instance to the TRACKER_HOMES variable as <code class="docutils literal"><span class="pre">'name':</span> <span class="pre">'home'</span></code></dd>
  608 </dl>
  609 <p>The “name” part of the configuration will appear in the URL and identifies the
  610 tracker (so you may have more than one tracker per cgi-bin script). Make sure
  611 there are no spaces or other illegal characters in it (to be safe, stick to
  612 letters and numbers). The “name” forms part of the URL that appears in the
  613 tracker config “tracker :: web” variable, so make sure they match. The “home”
  614 part of the configuration is the tracker home directory.</p>
  615 <p>If you’re using Apache, you can use an additional trick to hide the
  616 <code class="docutils literal"><span class="pre">.cgi</span></code> extension of the cgi script. Place the <code class="docutils literal"><span class="pre">roundup.cgi</span></code> script
  617 wherever you want it to be, rename it to just <code class="docutils literal"><span class="pre">roundup</span></code>, and add a
  618 couple lines to your Apache configuration:</p>
  619 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">Location</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">roundup</span><span class="o">&gt;</span>
  620   <span class="n">SetHandler</span> <span class="n">cgi</span><span class="o">-</span><span class="n">script</span>
  621 <span class="o">&lt;/</span><span class="n">Location</span><span class="o">&gt;</span>
  622 </pre></div>
  623 </div>
  624 </div>
  625 <div class="section" id="cgi-bin-for-limited-access-hosting">
  626 <h4>CGI-bin for Limited-Access Hosting<a class="headerlink" href="#cgi-bin-for-limited-access-hosting" title="Permalink to this headline"></a></h4>
  627 <p>If you are running in a shared-hosting environment or otherwise don’t have
  628 permission to edit the system web server’s configuration, but can create a
  629 <code class="docutils literal"><span class="pre">.htaccess</span></code> file then you may be able to use this approach.</p>
  630 <ol class="arabic">
  631 <li><p class="first">Install <a class="reference external" href="https://pypi.org/project/flup/">flup</a></p>
  632 </li>
  633 <li><p class="first">Create a script <code class="docutils literal"><span class="pre">roundup_stub</span></code> in your server’s <code class="docutils literal"><span class="pre">cgi-bin</span></code> directory
  634 containing:</p>
  635 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
  636 
  637 <span class="c1"># if necessary modify the Python path to include the place you</span>
  638 <span class="c1"># installed Roundup</span>
  639 <span class="c1">#import sys</span>
  640 <span class="c1">#sys.path.append(&#39;...&#39;)</span>
  641 
  642 <span class="c1"># cgitb is needed for debugging in browser only</span>
  643 <span class="c1">#import cgitb</span>
  644 <span class="c1">#cgitb.enable()</span>
  645 
  646 <span class="c1"># obtain the WSGI request dispatcher</span>
  647 <span class="kn">from</span> <span class="nn">roundup.cgi.wsgi_handler</span> <span class="k">import</span> <span class="n">RequestDispatcher</span>
  648 <span class="n">tracker_home</span> <span class="o">=</span> <span class="s1">&#39;/path/to/tracker/home&#39;</span>
  649 <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>
  650 
  651 <span class="kn">from</span> <span class="nn">flup.server.cgi</span> <span class="k">import</span> <span class="n">WSGIServer</span>
  652 <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>
  653 </pre></div>
  654 </div>
  655 </li>
  656 <li><p class="first">Modify or created the <code class="docutils literal"><span class="pre">.htaccess</span></code> file in the desired (sub-)domain
  657 directory to contain:</p>
  658 <div class="highlight-default"><div class="highlight"><pre><span></span>RewriteEngine On
  659 RewriteBase /
  660 RewriteRule ^(.*)$      /cgi-bin/roundup_stub/$1 [L]
  661 </pre></div>
  662 </div>
  663 </li>
  664 </ol>
  665 <p>Now loading the (sub-)domain in a browser should load the tracker web
  666 interface. If you get a “500” error then enable the “cgitb” lines in the
  667 stub to get some debugging information.</p>
  668 </div>
  669 <div class="section" id="stand-alone-web-server">
  670 <span id="index-6"></span><h4>Stand-alone Web Server<a class="headerlink" href="#stand-alone-web-server" title="Permalink to this headline"></a></h4>
  671 <p>This approach will give you faster response than cgi-bin. You may
  672 investigate using ProxyPass or similar configuration in apache to have your
  673 tracker accessed through the same URL as other systems.</p>
  674 <p>The stand-alone web server is started with the command <code class="docutils literal"><span class="pre">roundup-server</span></code>. It
  675 has several options - display them with <code class="docutils literal"><span class="pre">roundup-server</span> <span class="pre">-h</span></code>.</p>
  676 <p>The tracker home configuration is similar to the cgi-bin - you may either edit
  677 the script to change the TRACKER_HOMES variable or you may supply the
  678 name=home values on the command-line after all the other options.</p>
  679 <p>To make the server run in the background, use the “-d” option, specifying the
  680 name of a file to write the server process id (pid) to.</p>
  681 </div>
  682 <div class="section" id="zope-product-zroundup">
  683 <span id="index-7"></span><h4>Zope Product - ZRoundup<a class="headerlink" href="#zope-product-zroundup" title="Permalink to this headline"></a></h4>
  684 <p>ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
  685 your Products directory either in INSTANCE_HOME/Products or the Zope
  686 code tree lib/python/Products.</p>
  687 <p>When you next (re)start up Zope, you will be able to add a ZRoundup object
  688 that interfaces to your new tracker.</p>
  689 </div>
  690 <div class="section" id="apache-http-server-with-mod-wsgi">
  691 <span id="index-8"></span><h4>Apache HTTP Server with mod_wsgi<a class="headerlink" href="#apache-http-server-with-mod-wsgi" title="Permalink to this headline"></a></h4>
  692 <p>This is a work in progress thanks to Garth Jensen.</p>
  693 <p>See the main web site for <a class="reference external" href="https://pypi.org/project/mod-wsgi/">mod_wsgi</a> which include directions for
  694 using mod_wsgi-express which is easier if you are not used to apache
  695 configuration. Also there is the
  696 <a class="reference external" href="https://modwsgi.readthedocs.io/en/develop/">main mod_wsgi</a> for more
  697 detailed directions.</p>
  698 <div class="section" id="background">
  699 <h5>Background<a class="headerlink" href="#background" title="Permalink to this headline"></a></h5>
  700 <p>These notes were developed on a Microsoft Azure VM running Ubuntu
  701 18.04 LTS.  The instructions below assume:</p>
  702 <ul class="simple">
  703 <li>python and roundup are already installed</li>
  704 <li>roundup is running in the system python instance (e.g. no virtual
  705 environment)</li>
  706 <li>the tracker <code class="docutils literal"><span class="pre">mytracker</span></code> is installed in the <code class="docutils literal"><span class="pre">trackers</span></code> folder of
  707 home directory of a user called <code class="docutils literal"><span class="pre">admin</span></code>. Thus, the absolute path to
  708 the tracker home directory is <code class="docutils literal"><span class="pre">/home/admin/trackers/mytracker</span></code>.</li>
  709 <li>the server has a static public IP address of 11.11.11.101</li>
  710 </ul>
  711 </div>
  712 <div class="section" id="install-mod-wsgi">
  713 <h5>Install mod-wsgi<a class="headerlink" href="#install-mod-wsgi" title="Permalink to this headline"></a></h5>
  714 <p>You can install/build it using the python package manager pip, or
  715 install using the OS package manager (apt).</p>
  716 <div class="section" id="pip-install-of-mod-wsgi">
  717 <h6>Pip install of mod_wsgi<a class="headerlink" href="#pip-install-of-mod-wsgi" title="Permalink to this headline"></a></h6>
  718 <p>This is the tested method, and offers an easier path to get started,
  719 but it does mean that you will need to keep up to date with any
  720 security or other issues. If you use the packages supplied by your OS
  721 vendor, you may get more timely updates and notifications.</p>
  722 <p>The mod_wsgi docs talk about two installation methods: (1) the
  723 so-called CMMI method or (2) with pip. The pip method also provides an
  724 admin script called <code class="docutils literal"><span class="pre">mod_wsgi-express</span></code> that can start up a
  725 standalone instance of Apache directly from the command line with an
  726 auto generated configuration. These instructions follow the pip
  727 method.</p>
  728 <ol class="arabic">
  729 <li><p class="first">The <a class="reference external" href="https://pypi.org/project/mod-wsgi/">mod_wsgi</a> PyPi page lists prerequisites for various types of
  730 systems. For Ubuntu, they are apache2 and apache2-dev. To see
  731 installed apache packages, you can use <code class="docutils literal"><span class="pre">dpkg</span> <span class="pre">-l</span> <span class="pre">|</span> <span class="pre">grep</span> <span class="pre">apache</span></code>.
  732 If apache2 or apache2-dev are not installed, they install them
  733 with:</p>
  734 <ul class="simple">
  735 <li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">update</span></code></li>
  736 <li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">apache2</span> <span class="pre">apache2-dev</span></code></li>
  737 </ul>
  738 </li>
  739 <li><p class="first">If <code class="docutils literal"><span class="pre">pip</span></code> is not already installed, install it with
  740 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">python-pip</span></code></p>
  741 <p>If you are using python 3, use <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt-install</span> <span class="pre">python3-pip</span></code> and
  742 change references to pip in the directions to pip3.</p>
  743 </li>
  744 <li><p class="first"><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">mod_wsgi</span></code>. In my case, I got warnings about
  745 the user not owning directories, but it said it completed
  746 “successfully.”</p>
  747 </li>
  748 <li><p class="first">For testing, open port 8000 for TCP on the server. For an Azure VM,
  749 this is done with Azure Portal under <code class="docutils literal"><span class="pre">Networking</span></code> &gt; <code class="docutils literal"><span class="pre">Add</span> <span class="pre">inbound</span> <span class="pre">port</span></code>
  750 rule.</p>
  751 </li>
  752 <li><p class="first">Test with <code class="docutils literal"><span class="pre">mod_wsgi-express</span> <span class="pre">start-server</span></code>. This should serve
  753 up content on localhost port 8000. You can then direct a browser on
  754 the server itself to <a class="reference external" href="http://localhost:8000/">http://localhost:8000/</a> or on another machine at
  755 the server’s domain name or ip address followed by colon then 8000
  756 (e.g. <a class="reference external" href="http://11.11.11.101:8000/">http://11.11.11.101:8000/</a>). If successful, you should see a
  757 Malt Whiskey image.</p>
  758 </li>
  759 </ol>
  760 </div>
  761 <div class="section" id="package-manager-install-of-mod-wsgi">
  762 <h6>Package manager install of mod_wsgi<a class="headerlink" href="#package-manager-install-of-mod-wsgi" title="Permalink to this headline"></a></h6>
  763 <p>On debian (which should work for Ubuntu), install apache2 with
  764 libapache2-mod-wsgi:</p>
  765 <blockquote>
  766 <div><ul class="simple">
  767 <li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">update</span></code></li>
  768 <li><code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">apache2</span> <span class="pre">libapache2-mod-wsgi</span></code></li>
  769 </ul>
  770 </div></blockquote>
  771 <p>this is the less tested method for installing mod_wsgi and may not
  772 install mod_wsgi-express, which is used below. However there is an
  773 example apache config included as part of <a class="reference internal" href="#wsgi-variations">WSGI Variations</a> that can
  774 be used to hand craft an apache config.</p>
  775 <p>You should make sure that the version you install is 3.5 or newer due
  776 to security issues in older releases.</p>
  777 </div>
  778 </div>
  779 <div class="section" id="configure-web-interface-via-wsgi-handler">
  780 <h5>Configure web interface via wsgi_handler<a class="headerlink" href="#configure-web-interface-via-wsgi-handler" title="Permalink to this headline"></a></h5>
  781 <ol class="arabic">
  782 <li><p class="first">In the tracker’s home directory create a <code class="docutils literal"><span class="pre">wsgi.py</span></code> file with the
  783 following content (substituting <code class="docutils literal"><span class="pre">/home/admin/trackers/mytracker</span></code>
  784 with the absolute path for your tracker’s home directory):</p>
  785 <div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">roundup.cgi.wsgi_handler</span> <span class="k">import</span> <span class="n">RequestDispatcher</span>
  786 <span class="n">tracker_home</span> <span class="o">=</span> <span class="s1">&#39;/home/admin/trackers/mytracker&#39;</span>
  787 <span class="n">application</span> <span class="o">=</span> <span class="n">RequestDispatcher</span><span class="p">(</span><span class="n">tracker_home</span><span class="p">)</span>
  788 </pre></div>
  789 </div>
  790 </li>
  791 </ol>
  792 </div>
  793 <div class="section" id="to-run-the-tracker-on-port-8000-as-a-foreground-process">
  794 <h5>To run the tracker on Port 8000 as a foreground process<a class="headerlink" href="#to-run-the-tracker-on-port-8000-as-a-foreground-process" title="Permalink to this headline"></a></h5>
  795 <ol class="arabic simple">
  796 <li>Change the <code class="docutils literal"><span class="pre">tracker.web</span></code> url in <code class="docutils literal"><span class="pre">config.ini</span></code> to port 8000 at the
  797 server domain name or ip address (e.g. <a class="reference external" href="http://11.11.11.101:8000/">http://11.11.11.101:8000/</a>).</li>
  798 <li>Open port 8000 for TCP on the server if you didn’t already do so.</li>
  799 <li><code class="docutils literal"><span class="pre">cd</span></code> to your tracker home directory, then run
  800 <code class="docutils literal"><span class="pre">mod_wsgi-express</span> <span class="pre">start-server</span> <span class="pre">wsgi.py</span></code>.</li>
  801 <li>Test by directing a browser on another machine to the url you set
  802 <code class="docutils literal"><span class="pre">tracker.web</span></code> to in <code class="docutils literal"><span class="pre">config.ini</span></code>.</li>
  803 </ol>
  804 </div>
  805 <div class="section" id="run-tracker-as-background-daemon">
  806 <h5>Run tracker as background daemon<a class="headerlink" href="#run-tracker-as-background-daemon" title="Permalink to this headline"></a></h5>
  807 <p>To run the tracker on Port 80 or as a background process, you’ll need
  808 to configure a UNIX group with appropriate privileges as described in
  809 <a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a>. These steps are summarized here:</p>
  810 <ol class="arabic simple">
  811 <li>To add a group named “mytrackergrp” run: <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">groupadd</span> <span class="pre">mytrackergrp</span></code>.</li>
  812 <li>Add the owner of the tracker home (admin in this example) run:
  813 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">usermod</span> <span class="pre">-a</span> <span class="pre">-G</span> <span class="pre">mytrackergrp</span> <span class="pre">admin</span></code></li>
  814 <li>Add user that runs Apache (the default on Ubuntu is www-data) run:
  815 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">usermod</span> <span class="pre">-a</span> <span class="pre">-G</span> <span class="pre">mytrackergrp</span> <span class="pre">www-data</span></code></li>
  816 <li>Add user mail service runs as (e.g. daemon) run:
  817 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">usermod</span> <span class="pre">-a</span> <span class="pre">-G</span> <span class="pre">mytrackergrp</span> <span class="pre">daemon</span></code></li>
  818 <li>Change group of the database in the tracker folder run:
  819 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">chgrp</span> <span class="pre">-R</span> <span class="pre">mytrackergrp</span> <span class="pre">~/trackers/mytracker</span></code>.</li>
  820 <li>Make sure group can write to the database, and any new files created
  821 in the database will be owned by the group run:
  822 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">chmod</span> <span class="pre">-R</span> <span class="pre">g+sw</span> <span class="pre">~/trackers/mytracker/db</span></code></li>
  823 </ol>
  824 </div>
  825 <div class="section" id="to-run-mod-wsgi-on-port-80">
  826 <h5>To run mod_wsgi on PORT 80<a class="headerlink" href="#to-run-mod-wsgi-on-port-80" title="Permalink to this headline"></a></h5>
  827 <ol class="arabic simple">
  828 <li>Change the <code class="docutils literal"><span class="pre">tracker.web</span></code> url in <code class="docutils literal"><span class="pre">config.ini</span></code> to the server url
  829 with no port designator. E.g. <a class="reference external" href="http://11.11.11.101">http://11.11.11.101</a>.</li>
  830 <li>Open port 80 on the server for TCP traffic if it isn’t open already.</li>
  831 <li>Stop the system instance of Apache to make sure it isn’t holding on
  832 to port 80 run: <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">service</span> <span class="pre">apache2</span> <span class="pre">stop</span></code>.</li>
  833 </ol>
  834 <div class="section" id="to-run-as-a-foreground-process">
  835 <h6>To run as a foreground process<a class="headerlink" href="#to-run-as-a-foreground-process" title="Permalink to this headline"></a></h6>
  836 <ol class="arabic simple">
  837 <li>From the tracker home directory, run
  838 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">mod_wsgi-express</span> <span class="pre">start-server</span> <span class="pre">wsgi.py</span> <span class="pre">--port</span> <span class="pre">80</span> <span class="pre">--user</span> <span class="pre">admin</span> <span class="pre">--group</span> <span class="pre">mytrackergrp</span></code></li>
  839 </ol>
  840 </div>
  841 <div class="section" id="to-run-as-a-background-process">
  842 <h6>To run as a background process<a class="headerlink" href="#to-run-as-a-background-process" title="Permalink to this headline"></a></h6>
  843 <ol class="arabic simple">
  844 <li>From the tracker home directory, bash
  845 <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">mod_wsgi-express</span> <span class="pre">setup-server</span> <span class="pre">wsgi.py</span> <span class="pre">--port=80</span> <span class="pre">--user</span> <span class="pre">admin</span> <span class="pre">--group</span> <span class="pre">mytrackergrp</span> <span class="pre">--server-root=/etc/mod_wsgi-express-80</span></code></li>
  846 <li>Then, run <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">/etc/mod_wsgi-express-80/apachectl</span> <span class="pre">start</span></code></li>
  847 <li>To stop, run <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">/etc/mod_wsgi-express-80/apachectl</span> <span class="pre">stop</span></code></li>
  848 </ol>
  849 </div>
  850 </div>
  851 </div>
  852 <div class="section" id="apache-http-server-with-mod-python">
  853 <span id="index-9"></span><h4>Apache HTTP Server with mod_python<a class="headerlink" href="#apache-http-server-with-mod-python" title="Permalink to this headline"></a></h4>
  854 <p>As of roundup 2.0, mod_python support is deprecated. The apache.py
  855 file is still available, but may be limited to working for Python 2
  856 only. Using mod_wsgi with Apache is the recommended way to deploy
  857 roundup under apache.</p>
  858 <p><a class="reference external" href="http://modpython.org/">Mod_python</a> is an <a class="reference external" href="http://httpd.apache.org/">Apache</a> module that embeds the Python interpreter
  859 within the server.  Running Roundup this way is much faster than all
  860 above options and, like <a class="reference internal" href="#web-server-cgi-bin">web server cgi-bin</a>, allows you to use HTTPS
  861 protocol.  The drawback is that this setup is more complicated.</p>
  862 <p>The following instructions were tested on apache 2.0 with mod_python 3.1.
  863 If you are using older versions, your mileage may vary.</p>
  864 <p>Mod_python uses OS threads.  If your apache was built without threads
  865 (quite commonly), you must load the threading library to run mod_python.
  866 This is done by setting <code class="docutils literal"><span class="pre">LD_PRELOAD</span></code> to your threading library path
  867 in apache <code class="docutils literal"><span class="pre">envvars</span></code> file.  Example for gentoo linux (<code class="docutils literal"><span class="pre">envvars</span></code> file
  868 is located in <code class="docutils literal"><span class="pre">/usr/lib/apache2/build/</span></code>):</p>
  869 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">LD_PRELOAD</span><span class="o">=/</span><span class="n">lib</span><span class="o">/</span><span class="n">libpthread</span><span class="o">.</span><span class="n">so</span><span class="o">.</span><span class="mi">0</span>
  870 <span class="n">export</span> <span class="n">LD_PRELOAD</span>
  871 </pre></div>
  872 </div>
  873 <p>Example for FreeBSD (<code class="docutils literal"><span class="pre">envvars</span></code> is in <code class="docutils literal"><span class="pre">/usr/local/sbin/</span></code>):</p>
  874 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">LD_PRELOAD</span><span class="o">=/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">libc_r</span><span class="o">.</span><span class="n">so</span>
  875 <span class="n">export</span> <span class="n">LD_PRELOAD</span>
  876 </pre></div>
  877 </div>
  878 <p>Next, you have to add Roundup trackers configuration to apache config.
  879 Roundup apache interface uses the following options specified with
  880 <code class="docutils literal"><span class="pre">PythonOption</span></code> directives:</p>
  881 <blockquote>
  882 <div><dl class="docutils">
  883 <dt>TrackerHome:</dt>
  884 <dd>defines the tracker home directory - the directory that was specified
  885 when you did <code class="docutils literal"><span class="pre">roundup-admin</span> <span class="pre">init</span></code>.  This option is required.</dd>
  886 <dt>TrackerLanguage:</dt>
  887 <dd>defines web user interface language.  mod_python applications do not
  888 receive OS environment variables in the same way as command-line
  889 programs, so the language cannot be selected by setting commonly
  890 used variables like <code class="docutils literal"><span class="pre">LANG</span></code> or <code class="docutils literal"><span class="pre">LC_ALL</span></code>.  <code class="docutils literal"><span class="pre">TrackerLanguage</span></code>
  891 value has the same syntax as values of these environment variables.
  892 This option may be omitted.</dd>
  893 <dt>TrackerDebug:</dt>
  894 <dd>run the tracker in debug mode.  Setting this option to <code class="docutils literal"><span class="pre">yes</span></code> or
  895 <code class="docutils literal"><span class="pre">true</span></code> has the same effect as running <code class="docutils literal"><span class="pre">roundup-server</span> <span class="pre">-t</span> <span class="pre">debug</span></code>:
  896 the database schema and used html templates are rebuilt for each
  897 HTTP request.  Values <code class="docutils literal"><span class="pre">no</span></code> or <code class="docutils literal"><span class="pre">false</span></code> mean that all html
  898 templates for the tracker are compiled and the database schema is
  899 checked once at startup.  This is the default behaviour.</dd>
  900 <dt>TrackerTiming:</dt>
  901 <dd>has nearly the same effect as environment variable <code class="docutils literal"><span class="pre">CGI_SHOW_TIMING</span></code>
  902 for standalone roundup server.  The difference is that setting this
  903 option to <code class="docutils literal"><span class="pre">no</span></code> or <code class="docutils literal"><span class="pre">false</span></code> disables timings display.  Value
  904 <code class="docutils literal"><span class="pre">comment</span></code> writes request handling times in html comment, and
  905 any other non-empty value makes timing report visible.  By default,
  906 timing display is disabled.</dd>
  907 </dl>
  908 </div></blockquote>
  909 <p>In the following example we have two trackers set up in
  910 <code class="docutils literal"><span class="pre">/var/db/roundup/support</span></code> and <code class="docutils literal"><span class="pre">/var/db/roundup/devel</span></code> and accessed
  911 as <code class="docutils literal"><span class="pre">https://my.host/roundup/support/</span></code> and <code class="docutils literal"><span class="pre">https://my.host/roundup/devel/</span></code>
  912 respectively (provided Apache has been set up for SSL of course).
  913 Having them share same parent directory allows us to
  914 reduce the number of configuration directives.  Support tracker has
  915 russian user interface.  The other tracker (devel) has english user
  916 interface (default).</p>
  917 <p>Static files from <code class="docutils literal"><span class="pre">html</span></code> directory are served by apache itself - this
  918 is quicker and generally more robust than doing that from python.
  919 Everything else is aliased to dummy (non-existing) <code class="docutils literal"><span class="pre">py</span></code> file,
  920 which is handled by mod_python and our roundup module.</p>
  921 <p>Example mod_python configuration:</p>
  922 <div class="highlight-default"><div class="highlight"><pre><span></span>#################################################
  923 # Roundup Issue tracker
  924 #################################################
  925 # enable Python optimizations (like &#39;python -O&#39;)
  926 PythonOptimize On
  927 # let apache handle static files from &#39;html&#39; directories
  928 AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2
  929 # everything else is handled by roundup web UI
  930 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2
  931 # roundup requires a slash after tracker name - add it if missing
  932 RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/
  933 # common settings for all roundup trackers
  934 &lt;Directory /var/db/roundup/*&gt;
  935   Order allow,deny
  936   Allow from all
  937   AllowOverride None
  938   Options None
  939   AddHandler python-program .py
  940   PythonHandler roundup.cgi.apache
  941   # uncomment the following line to see tracebacks in the browser
  942   # (note that *some* tracebacks will be displayed anyway)
  943   #PythonDebug On
  944 &lt;/Directory&gt;
  945 # roundup tracker homes
  946 &lt;Directory /var/db/roundup/support&gt;
  947   PythonOption TrackerHome /var/db/roundup/support
  948   PythonOption TrackerLanguage ru
  949 &lt;/Directory&gt;
  950 &lt;Directory /var/db/roundup/devel&gt;
  951   PythonOption TrackerHome /var/db/roundup/devel
  952 &lt;/Directory&gt;
  953 </pre></div>
  954 </div>
  955 <p>Notice that the <code class="docutils literal"><span class="pre">/var/db/roundup</span></code> path shown above refers to the directory
  956 in which the tracker homes are stored. The actual value will thus depend on
  957 your system.</p>
  958 <p>On Windows the corresponding lines will look similar to these:</p>
  959 <div class="highlight-default"><div class="highlight"><pre><span></span>AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2
  960 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2
  961 &lt;Directory C:/DATA/roundup/*&gt;
  962 &lt;Directory C:/DATA/roundup/support&gt;
  963 &lt;Directory C:/DATA/roundup/devel&gt;
  964 </pre></div>
  965 </div>
  966 <p>In this example the directory hosting all of the tracker homes is
  967 <code class="docutils literal"><span class="pre">C:\DATA\roundup</span></code>. (Notice that you must use forward slashes in paths
  968 inside the httpd.conf file!)</p>
  969 <p>The URL for accessing these trackers then become:
  970 <cite>http://&lt;roundupserver&gt;/roundup/support/`</cite> and
  971 <code class="docutils literal"><span class="pre">http://&lt;roundupserver&gt;/roundup/devel/</span></code></p>
  972 <p>Note that in order to use https connections you must set up Apache for secure
  973 serving with SSL.</p>
  974 </div>
  975 <div class="section" id="wsgi-variations">
  976 <h4>WSGI Variations<a class="headerlink" href="#wsgi-variations" title="Permalink to this headline"></a></h4>
  977 <div class="section" id="apache-alternate">
  978 <span id="index-10"></span><h5>Apache Alternate<a class="headerlink" href="#apache-alternate" title="Permalink to this headline"></a></h5>
  979 <p>This method from Thomas Arendsen Hein goes into a bit more detail and
  980 is designed to allow you to run multiple roundup trackers each under
  981 their own user.</p>
  982 <p>The tracker instances are read-only to the tracker user and located
  983 under /srv/roundup/.  The (writable) data files are stored in the home
  984 directory of the user running the tracker.</p>
  985 <p>To install roundup, download and unpack a distribution tarball and run
  986 the following as user “roundup”:</p>
  987 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build_doc</span>
  988 <span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span> <span class="o">--</span><span class="n">manifest</span><span class="o">-</span><span class="n">only</span>
  989 <span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span> <span class="o">--</span><span class="n">home</span><span class="o">=</span><span class="s2">&quot;/home/roundup/install&quot;</span> <span class="o">--</span><span class="n">force</span>
  990 </pre></div>
  991 </div>
  992 <p>Create a user roundup-foo, group roundup-foo to run the tracker.  Add
  993 the following apache config to
  994 /etc/apache2/sites-available/roundup-foo (under debian/Ubunutu, modify
  995 as needed):</p>
  996 <blockquote>
  997 <div><div class="code xml highlight-default"><div class="highlight"><pre><span></span>ServerAdmin webmaster@example.com
  998 ErrorLog /var/log/apache2/error.log
  999 
 1000 LogLevel notice
 1001 
 1002 DocumentRoot /var/www/
 1003 
 1004 &lt;VirtualHost *:80&gt;
 1005         CustomLog /var/log/apache2/access.log vhost_combined
 1006 
 1007         # allow access to roundup docs
 1008         Alias /doc/ /home/roundup/install/share/doc/roundup/html/
 1009 
 1010         # make apache serve static assets like css rather than
 1011         # having roundup serve the files
 1012         Alias /foo/@@file/ /srv/roundup/foo/html/
 1013 
 1014         # make /foo into /foo/
 1015         RedirectMatch permanent ^/(foo)$ /$1/
 1016 
 1017         # start a wsgi daemon process running as user roundup-foo
 1018         # in group roundup-foo. This also changes directory to
 1019         # ~roundup-foo before it starts roundup.wsgi.
 1020         WSGIDaemonProcess roundup-foo display-name=roundup-foo user=roundup-foo group=roundup-foo threads=25
 1021 
 1022         # make tracker available at /foo and tie it into the
 1023         # wsgi script below.
 1024         WSGIScriptAlias /foo /srv/roundup/foo/roundup.wsgi
 1025         &lt;Location /foo&gt;
 1026                 WSGIProcessGroup roundup-foo
 1027         &lt;/Location&gt;
 1028 &lt;/VirtualHost&gt;
 1029 </pre></div>
 1030 </div>
 1031 </div></blockquote>
 1032 <p>The directory ~roundup-foo should have:</p>
 1033 <blockquote>
 1034 <div><ul class="simple">
 1035 <li>a <code class="docutils literal"><span class="pre">db</span></code> subdirectory where messages and files will be stored</li>
 1036 <li>a symbolic link called <code class="docutils literal"><span class="pre">instance</span></code> to /srv/roundup/foo which has
 1037 been initialized using <code class="docutils literal"><span class="pre">roundup-admin</span></code>.</li>
 1038 </ul>
 1039 </div></blockquote>
 1040 <p>The <a class="reference internal" href="#apache-http-server-with-mod-wsgi">Apache HTTP Server with mod_wsgi</a> section above has a simple
 1041 WSGI handler.  This is an enhanced version to be put into
 1042 <code class="docutils literal"><span class="pre">/srv/roundup/foo/roundup.wsgi</span></code>.</p>
 1043 <blockquote>
 1044 <div><div class="code python highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">sys</span><span class="o">,</span> <span class="nn">os</span>
 1045 <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">stderr</span>
 1046 
 1047 <span class="n">enabled</span> <span class="o">=</span> <span class="kc">True</span>
 1048 
 1049 <span class="k">if</span> <span class="n">enabled</span><span class="p">:</span>
 1050     <span class="c1"># Add the directory with the roundup installation</span>
 1051     <span class="c1"># subdirectory to the python path.</span>
 1052     <span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s1">&#39;/home/roundup/install/lib/python&#39;</span><span class="p">)</span>
 1053 
 1054     <span class="c1"># obtain the WSGI request dispatcher</span>
 1055     <span class="kn">from</span> <span class="nn">roundup.cgi.wsgi_handler</span> <span class="k">import</span> <span class="n">RequestDispatcher</span>
 1056 
 1057     <span class="n">tracker_home</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">getcwd</span><span class="p">(),</span> <span class="s1">&#39;instance&#39;</span><span class="p">)</span>
 1058     <span class="n">application</span> <span class="o">=</span> <span class="n">RequestDispatcher</span><span class="p">(</span><span class="n">tracker_home</span><span class="p">)</span>
 1059 <span class="k">else</span><span class="p">:</span>
 1060     <span class="k">def</span> <span class="nf">application</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">):</span>
 1061         <span class="n">status</span> <span class="o">=</span> <span class="s1">&#39;503 Service Unavailable&#39;</span>
 1062         <span class="n">output</span> <span class="o">=</span> <span class="s1">&#39;service is down for maintenance&#39;</span>
 1063         <span class="n">response_headers</span> <span class="o">=</span> <span class="p">[(</span><span class="s1">&#39;Content-type&#39;</span><span class="p">,</span> <span class="s1">&#39;text/plain&#39;</span><span class="p">),</span>
 1064                             <span class="p">(</span><span class="s1">&#39;Content-Length&#39;</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">output</span><span class="p">)))]</span>
 1065         <span class="n">start_response</span><span class="p">(</span><span class="n">status</span><span class="p">,</span> <span class="n">response_headers</span><span class="p">)</span>
 1066         <span class="k">return</span> <span class="p">[</span><span class="n">output</span><span class="p">]</span>
 1067 </pre></div>
 1068 </div>
 1069 </div></blockquote>
 1070 <p>This handler allows you to temporarily disable the tracker by setting
 1071 “enabled = False”, apache will automatically detect the changed
 1072 roundup.wsgi file and reload it.</p>
 1073 <p>One last change is needed. In the tracker’s config.ini change the db
 1074 parameter in the [main] section to be /home/roundup-foo/db. This will
 1075 put the files and messages in the db directory for the user.</p>
 1076 </div>
 1077 <div class="section" id="gunicorn-installation">
 1078 <span id="index-11"></span><h5>Gunicorn Installation<a class="headerlink" href="#gunicorn-installation" title="Permalink to this headline"></a></h5>
 1079 <p>To run with gunicorn use pip to install gunicorn. This configuration
 1080 uses a front end web server like nginx, hiawatha, apache configured as
 1081 a reverse proxy. See your web server’s documentation on how to set it
 1082 up as a reverse proxy.</p>
 1083 <p>The file wsgi.py should be in the current directory with the
 1084 contents:</p>
 1085 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># if roundup is not installed on the default PYTHONPATH</span>
 1086 <span class="c1"># set it here with:</span>
 1087 <span class="kn">import</span> <span class="nn">sys</span>
 1088 <span class="n">sys</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;/path/to/roundup/install/directory&#39;</span><span class="p">)</span>
 1089 
 1090 <span class="c1"># obtain the WSGI request dispatcher</span>
 1091 <span class="kn">from</span> <span class="nn">roundup.cgi.wsgi_handler</span> <span class="k">import</span> <span class="n">RequestDispatcher</span>
 1092 <span class="n">tracker_home</span> <span class="o">=</span> <span class="s1">&#39;/path/to/tracker/install/directory&#39;</span>
 1093 
 1094 <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>
 1095 </pre></div>
 1096 </div>
 1097 <p>Assuming the proxy forwards /tracker, run gunicorn as:</p>
 1098 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">SCRIPT_NAME</span><span class="o">=/</span><span class="n">tracker</span> <span class="n">gunicorn</span> <span class="o">--</span><span class="n">bind</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span><span class="p">:</span><span class="mi">8917</span> <span class="o">--</span><span class="n">timeout</span><span class="o">=</span><span class="mi">10</span> <span class="n">wsgi</span><span class="p">:</span><span class="n">app</span>
 1099 </pre></div>
 1100 </div>
 1101 <p>this runs roundup at port 8917 on the loopback interface. You should
 1102 configure the reverse proxy to talk to 127.0.0.1 at port 8917.</p>
 1103 </div>
 1104 <div class="section" id="uwsgi-installation">
 1105 <span id="index-12"></span><h5>uWSGI Installation<a class="headerlink" href="#uwsgi-installation" title="Permalink to this headline"></a></h5>
 1106 <p>For a basic roundup install using uWSGI behind a front end server,
 1107 install uwsgi and the python3 (or python) plugin. Then run:</p>
 1108 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">uwsgi</span> <span class="o">--</span><span class="n">http</span><span class="o">-</span><span class="n">socket</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span><span class="p">:</span><span class="mi">8917</span> \
 1109     <span class="o">--</span><span class="n">plugin</span> <span class="n">python3</span> <span class="o">--</span><span class="n">mount</span><span class="o">=/</span><span class="n">tracker</span><span class="o">=</span><span class="n">wsgi</span><span class="o">.</span><span class="n">py</span> \
 1110     <span class="o">--</span><span class="n">manage</span><span class="o">-</span><span class="n">script</span><span class="o">-</span><span class="n">name</span> <span class="o">--</span><span class="n">callable</span> <span class="n">app</span>
 1111 </pre></div>
 1112 </div>
 1113 <p>using the same wsgi.py as was used for gunicorn. If you get path not
 1114 found errors, check the mount option. The /tracker entry must match
 1115 the path used for the [tracker] web value in the tracker’s config.ini.</p>
 1116 </div>
 1117 </div>
 1118 </div>
 1119 <div class="section" id="configure-an-email-interface">
 1120 <h3><a class="toc-backref" href="#id14">Configure an Email Interface</a><a class="headerlink" href="#configure-an-email-interface" title="Permalink to this headline"></a></h3>
 1121 <p>If you don’t want to use the email component of Roundup, then remove the
 1122 <code class="docutils literal"><span class="pre">nosyreaction.py</span></code>” module from your tracker “<code class="docutils literal"><span class="pre">detectors</span></code>” directory.</p>
 1123 <p>See <a class="reference internal" href="#platform-specific-notes">platform-specific notes</a> for steps that may be needed on your system.</p>
 1124 <p>There are five supported ways to get emailed issues into the
 1125 Roundup tracker.  You should pick ONE of the following, all
 1126 of which will continue my example setup from above:</p>
 1127 <div class="section" id="as-a-mail-alias-pipe-process">
 1128 <h4>As a mail alias pipe process<a class="headerlink" href="#as-a-mail-alias-pipe-process" title="Permalink to this headline"></a></h4>
 1129 <p>Set up a mail alias called “issue_tracker” as (include the quote marks):
 1130 <code class="docutils literal"><span class="pre">|/usr/bin/python</span> <span class="pre">/usr/bin/roundup-mailgw</span> <span class="pre">&lt;tracker_home&gt;</span></code>
 1131 (substitute <code class="docutils literal"><span class="pre">/usr/bin</span></code> for wherever roundup-mailgw is installed).</p>
 1132 <p>In some installations (e.g. RedHat Linux and Fedora Core) you’ll need to
 1133 set up smrsh so sendmail will accept the pipe command. In that case,
 1134 symlink <code class="docutils literal"><span class="pre">/etc/smrsh/roundup-mailgw</span></code> to “<code class="docutils literal"><span class="pre">/usr/bin/roundup-mailgw</span></code>
 1135 and change the command to:</p>
 1136 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">|</span><span class="n">roundup</span><span class="o">-</span><span class="n">mailgw</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><span class="o">/</span><span class="n">support</span>
 1137 </pre></div>
 1138 </div>
 1139 <p>To test the mail gateway on unix systems, try:</p>
 1140 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">echo</span> <span class="n">test</span> <span class="o">|</span><span class="n">mail</span> <span class="o">-</span><span class="n">s</span> <span class="s1">&#39;[issue] test&#39;</span> <span class="n">support</span><span class="nd">@YOUR_DOMAIN_HERE</span>
 1141 </pre></div>
 1142 </div>
 1143 <p>Be careful that some mail systems (postfix for example) will impost a
 1144 limits on processes they spawn. In particular postfix can set a file size
 1145 limit. <em>This can cause your Roundup database to become corrupted.</em></p>
 1146 </div>
 1147 <div class="section" id="as-a-custom-router-transport-using-a-pipe-process-exim4-specific">
 1148 <h4>As a custom router/transport using a pipe process (Exim4 specific)<a class="headerlink" href="#as-a-custom-router-transport-using-a-pipe-process-exim4-specific" title="Permalink to this headline"></a></h4>
 1149 <p>The following configuration snippets for <a class="reference external" href="http://www.exim.org/">Exim 4</a> configuration
 1150 implement a custom router &amp; transport to accomplish mail delivery to
 1151 roundup-mailgw. A configuration for Exim3 is similar but not
 1152 included, since Exim3 is considered obsolete.</p>
 1153 <p>This configuration is similar to the previous section, in that it uses
 1154 a pipe process. However, there are advantages to using a custom
 1155 router/transport process, if you are using Exim.</p>
 1156 <ul class="simple">
 1157 <li>This avoids privilege escalation, since otherwise the pipe process
 1158 will run as the mail user, typically mail. The transport can be
 1159 configured to run as the user appropriate for the task at hand. In the
 1160 transport described in this section, Exim4 runs as the unprivileged
 1161 user <code class="docutils literal"><span class="pre">roundup</span></code>.</li>
 1162 <li>Separate configuration is not required for each tracker
 1163 instance. When a email arrives at the server, Exim passes it through
 1164 the defined routers. The roundup_router looks for a match with one of
 1165 the roundup directories, and if there is one it is passed to the
 1166 roundup_transport, which uses the pipe process described in the
 1167 previous section (<a class="reference internal" href="#as-a-mail-alias-pipe-process">As a mail alias pipe process</a>).</li>
 1168 </ul>
 1169 <p>The matching is done in the line:</p>
 1170 <div class="highlight-default"><div class="highlight"><pre><span></span>require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
 1171 </pre></div>
 1172 </div>
 1173 <p>The following configuration has been tested on Debian Sarge with
 1174 Exim4.</p>
 1175 <div class="admonition note">
 1176 <p class="first admonition-title">Note</p>
 1177 <p>Note that the Debian Exim4 packages don’t allow pipes in alias files
 1178 by default, so the method described in the section <a class="reference internal" href="#as-a-mail-alias-pipe-process">As a mail alias
 1179 pipe process</a> will not work with the default configuration. However,
 1180 the method described in this section does. See the discussion in
 1181 <code class="docutils literal"><span class="pre">/usr/share/doc/exim4-config/README.system_aliases</span></code> on any Debian
 1182 system with Exim4 installed.</p>
 1183 <p class="last">For more Debian-specific information, see suggested addition to
 1184 README.Debian in
 1185 <a class="reference external" href="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283">https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283</a>, which will
 1186 hopefully be merged into the Debian package eventually.</p>
 1187 </div>
 1188 <p>This config makes a few assumptions:</p>
 1189 <ul class="simple">
 1190 <li>That the mail address corresponding to the tracker instance has the
 1191 same name as the directory of the tracker instance, i.e. the mail
 1192 interface address corresponding to a Roundup instance called
 1193 <code class="docutils literal"><span class="pre">/var/lib/roundup/trackers/mytracker</span></code> is <code class="docutils literal"><span class="pre">mytracker&#64;your.host</span></code>.</li>
 1194 <li>That (at least) all the db subdirectories of all the tracker
 1195 instances (ie. <code class="docutils literal"><span class="pre">/var/lib/roundup/trackers/*/db</span></code>) are owned by the same
 1196 user, in this case, ‘roundup’.</li>
 1197 <li>That if the <code class="docutils literal"><span class="pre">schema.py</span></code> file exists, then the tracker is ready for
 1198 use. Another option is to use the <code class="docutils literal"><span class="pre">config.ini</span></code> file (this changed
 1199 in 0.8 from <code class="docutils literal"><span class="pre">config.py</span></code>).</li>
 1200 </ul>
 1201 <p>Macros for Roundup router/transport. Should be placed in the macros
 1202 section of the Exim4 config:</p>
 1203 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Home dir for your Roundup installation</span>
 1204 <span class="n">ROUNDUP_HOME</span><span class="o">=/</span><span class="n">var</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">roundup</span><span class="o">/</span><span class="n">trackers</span>
 1205 
 1206 <span class="c1"># User and group for Roundup.</span>
 1207 <span class="n">ROUNDUP_USER</span><span class="o">=</span><span class="n">roundup</span>
 1208 <span class="n">ROUNDUP_GROUP</span><span class="o">=</span><span class="n">roundup</span>
 1209 </pre></div>
 1210 </div>
 1211 <p>Custom router for Roundup. This will (probably) work if placed at the
 1212 beginning of the router section of the Exim4 config:</p>
 1213 <div class="highlight-default"><div class="highlight"><pre><span></span>roundup_router:
 1214     driver = accept
 1215     # The config file config.ini seems like a more natural choice, but the
 1216     # file config.py was replaced by config.ini in 0.8, and schema.py needs
 1217     # to be present too.
 1218     require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
 1219     transport = roundup_transport
 1220 </pre></div>
 1221 </div>
 1222 <p>Custom transport for Roundup. This will (probably) work if placed at
 1223 the beginning of the router section of the Exim4 config:</p>
 1224 <div class="highlight-default"><div class="highlight"><pre><span></span>roundup_transport:
 1225     driver = pipe
 1226     command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/
 1227     current_directory = ROUNDUP_HOME
 1228     home_directory = ROUNDUP_HOME
 1229     user = ROUNDUP_USER
 1230     group = ROUNDUP_GROUP
 1231 </pre></div>
 1232 </div>
 1233 </div>
 1234 <div class="section" id="as-a-regular-job-using-a-mailbox-source">
 1235 <h4>As a regular job using a mailbox source<a class="headerlink" href="#as-a-regular-job-using-a-mailbox-source" title="Permalink to this headline"></a></h4>
 1236 <p>Set <code class="docutils literal"><span class="pre">roundup-mailgw</span></code> up to run every 10 minutes or so. For example
 1237 (substitute <code class="docutils literal"><span class="pre">/usr/bin</span></code> for wherever roundup-mailgw is installed):</p>
 1238 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="mi">0</span><span class="p">,</span><span class="mi">10</span><span class="p">,</span><span class="mi">20</span><span class="p">,</span><span class="mi">30</span><span class="p">,</span><span class="mi">40</span><span class="p">,</span><span class="mi">50</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">roundup</span><span class="o">-</span><span class="n">mailgw</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><span class="o">/</span><span class="n">support</span> <span class="n">mailbox</span> <span class="o">&lt;</span><span class="n">mail_spool_file</span><span class="o">&gt;</span>
 1239 </pre></div>
 1240 </div>
 1241 <p>Where the <code class="docutils literal"><span class="pre">mail_spool_file</span></code> argument is the location of the roundup submission
 1242 user’s mail spool. On most systems, the spool for a user “issue_tracker”
 1243 will be “<code class="docutils literal"><span class="pre">/var/mail/issue_tracker</span></code>”.</p>
 1244 </div>
 1245 <div class="section" id="as-a-regular-job-using-a-pop-source">
 1246 <h4>As a regular job using a POP source<a class="headerlink" href="#as-a-regular-job-using-a-pop-source" title="Permalink to this headline"></a></h4>
 1247 <p>To retrieve from a POP mailbox, use a <em>cron</em> entry similar to the mailbox
 1248 one (substitute <code class="docutils literal"><span class="pre">/usr/bin</span></code> for wherever roundup-mailgw is
 1249 installed):</p>
 1250 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="mi">0</span><span class="p">,</span><span class="mi">10</span><span class="p">,</span><span class="mi">20</span><span class="p">,</span><span class="mi">30</span><span class="p">,</span><span class="mi">40</span><span class="p">,</span><span class="mi">50</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">roundup</span><span class="o">-</span><span class="n">mailgw</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><span class="o">/</span><span class="n">support</span> <span class="n">pop</span> <span class="o">&lt;</span><span class="n">pop_spec</span><span class="o">&gt;</span>
 1251 </pre></div>
 1252 </div>
 1253 <p>where pop_spec is “<code class="docutils literal"><span class="pre">username:password&#64;server</span></code>” that specifies the roundup
 1254 submission user’s POP account name, password and server.</p>
 1255 <p>On windows, you would set up the command using the windows scheduler.</p>
 1256 </div>
 1257 <div class="section" id="as-a-regular-job-using-an-imap-source">
 1258 <h4>As a regular job using an IMAP source<a class="headerlink" href="#as-a-regular-job-using-an-imap-source" title="Permalink to this headline"></a></h4>
 1259 <p>To retrieve from an IMAP mailbox, use a <em>cron</em> entry similar to the
 1260 POP one (substitute <code class="docutils literal"><span class="pre">/usr/bin</span></code> for wherever roundup-mailgw is
 1261 installed):</p>
 1262 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="mi">0</span><span class="p">,</span><span class="mi">10</span><span class="p">,</span><span class="mi">20</span><span class="p">,</span><span class="mi">30</span><span class="p">,</span><span class="mi">40</span><span class="p">,</span><span class="mi">50</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="o">*</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">roundup</span><span class="o">-</span><span class="n">mailgw</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><span class="o">/</span><span class="n">support</span> <span class="n">imap</span> <span class="o">&lt;</span><span class="n">imap_spec</span><span class="o">&gt;</span>
 1263 </pre></div>
 1264 </div>
 1265 <p>where imap_spec is “<code class="docutils literal"><span class="pre">username:password&#64;server</span></code>” that specifies the roundup
 1266 submission user’s IMAP account name, password and server. You may
 1267 optionally include a mailbox to use other than the default <code class="docutils literal"><span class="pre">INBOX</span></code> with
 1268 <code class="docutils literal"><span class="pre">imap</span> <span class="pre">username:password&#64;server</span> <span class="pre">mailbox</span></code>”.</p>
 1269 <p>If you have a secure (ie. HTTPS) IMAP server then you may use <code class="docutils literal"><span class="pre">imaps</span></code>
 1270 in place of <code class="docutils literal"><span class="pre">imap</span></code> in the command to use a secure connection.</p>
 1271 <p>As with the POP job, on windows, you would set up the command using the
 1272 windows scheduler.</p>
 1273 </div>
 1274 </div>
 1275 <div class="section" id="unix-environment-steps">
 1276 <h3><a class="toc-backref" href="#id15">UNIX Environment Steps</a><a class="headerlink" href="#unix-environment-steps" title="Permalink to this headline"></a></h3>
 1277 <p>Each tracker ideally should have its own UNIX group, so create
 1278 a UNIX group (edit <code class="docutils literal"><span class="pre">/etc/group</span></code> or your appropriate NIS map if
 1279 you’re using NIS).  To continue with my examples so far, I would
 1280 create the UNIX group ‘support’, although the name of the UNIX
 1281 group does not have to be the same as the tracker name.  To this
 1282 ‘support’ group I then add all of the UNIX usernames who will be
 1283 working with this Roundup tracker.  In addition to ‘real’ users,
 1284 the Roundup email gateway will need to have permissions to this
 1285 area as well, so add the user your mail service runs as to the
 1286 group (typically “mail” or “daemon”).  The UNIX group might then
 1287 look like:</p>
 1288 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">support</span><span class="p">:</span><span class="o">*</span><span class="p">:</span><span class="mi">1002</span><span class="p">:</span><span class="n">jblaine</span><span class="p">,</span><span class="n">samh</span><span class="p">,</span><span class="n">geezer</span><span class="p">,</span><span class="n">mail</span>
 1289 </pre></div>
 1290 </div>
 1291 <p>If you intend to use the web interface (as most people do), you
 1292 should also add the username your web server runs as to the group.
 1293 My group now looks like this:</p>
 1294 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">support</span><span class="p">:</span><span class="o">*</span><span class="p">:</span><span class="mi">1002</span><span class="p">:</span><span class="n">jblaine</span><span class="p">,</span><span class="n">samh</span><span class="p">,</span><span class="n">geezer</span><span class="p">,</span><span class="n">mail</span><span class="p">,</span><span class="n">apache</span>
 1295 </pre></div>
 1296 </div>
 1297 <p>The tracker “db” directory should be chmod’ed g+sw so that the group can
 1298 write to the database, and any new files created in the database will be owned
 1299 by the group.</p>
 1300 <p>If you’re using the mysql or postgresql backend then you’ll need to ensure
 1301 that the tracker user has appropriate permissions to create/modify the
 1302 database. If you’re using roundup.cgi, the apache user needs permissions
 1303 to modify the database.  Alternatively, explicitly specify a database login
 1304 in <code class="docutils literal"><span class="pre">rdbms</span></code> -&gt; <code class="docutils literal"><span class="pre">user</span></code> and <code class="docutils literal"><span class="pre">password</span></code> in <code class="docutils literal"><span class="pre">config.ini</span></code>.</p>
 1305 <p>An alternative to the above is to create a new user who has the sole
 1306 responsibility of running roundup. This user:</p>
 1307 <ol class="arabic simple">
 1308 <li>runs the CGI interface daemon</li>
 1309 <li>runs regular polls for email</li>
 1310 <li>runs regular checks (using cron) to ensure the daemon is up</li>
 1311 <li>optionally has no login password so that nobody but the “root” user
 1312 may actually login and play with the roundup setup.</li>
 1313 </ol>
 1314 <p>If you’re using a Linux system (e.g. Fedora Core) with SELinux enabled,
 1315 you will need to ensure that the db directory has a context that
 1316 permits the web server to modify and create files. If you’re using the
 1317 mysql or postgresql backend you may also need to update your policy to
 1318 allow the web server to access the database socket.</p>
 1319 </div>
 1320 <div class="section" id="public-tracker-considerations">
 1321 <h3><a class="toc-backref" href="#id16">Public Tracker Considerations</a><a class="headerlink" href="#public-tracker-considerations" title="Permalink to this headline"></a></h3>
 1322 <p>If you run a public tracker, you will eventually have to think about
 1323 dealing with spam entered through both the web and mail interfaces.</p>
 1324 <p>See the section on <a class="reference external" href="customizing.html#preventing-spam">Preventing SPAM</a> in the
 1325 <a class="reference external" href="customizing.html">customisation documentation</a> that has a simple detector
 1326 that will block lot of spam attempts.</p>
 1327 </div>
 1328 </div>
 1329 <div class="section" id="maintenance">
 1330 <h2><a class="toc-backref" href="#id17">Maintenance</a><a class="headerlink" href="#maintenance" title="Permalink to this headline"></a></h2>
 1331 <p>Read the separate <a class="reference external" href="admin_guide.html">administration guide</a> for information about how to
 1332 perform common maintenance tasks with Roundup.</p>
 1333 </div>
 1334 <div class="section" id="upgrading">
 1335 <h2><a class="toc-backref" href="#id18">Upgrading</a><a class="headerlink" href="#upgrading" title="Permalink to this headline"></a></h2>
 1336 <p>Read the separate <a class="reference external" href="upgrading.html">upgrading document</a>, which describes the steps needed to
 1337 upgrade existing tracker trackers for each version of Roundup that is
 1338 released.</p>
 1339 </div>
 1340 <div class="section" id="further-reading">
 1341 <h2><a class="toc-backref" href="#id19">Further Reading</a><a class="headerlink" href="#further-reading" title="Permalink to this headline"></a></h2>
 1342 <p>If you intend to use Roundup with anything other than the default
 1343 templates, if you would like to hack on Roundup, or if you would
 1344 like implementation details, you should read <a class="reference external" href="customizing.html">Customising Roundup</a>.</p>
 1345 </div>
 1346 <div class="section" id="running-multiple-trackers">
 1347 <h2><a class="toc-backref" href="#id20">Running Multiple Trackers</a><a class="headerlink" href="#running-multiple-trackers" title="Permalink to this headline"></a></h2>
 1348 <p>Things to think about before you jump off the deep end and install
 1349 multiple trackers, which involve additional URLs, user databases, email
 1350 addresses, databases to back up, etc.</p>
 1351 <ol class="arabic simple">
 1352 <li>Do you want a tracker per product you sell/support? You can just add
 1353 a new property to your issues called Product, and filter by that. See
 1354 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>
 1355 <li>Do you want to track internal software development issues and customer
 1356 support issues separately? You can just set up an additional “issue”
 1357 class called “cust_issues” in the same tracker, mimicing the normal
 1358 “issue” class, but with different properties. See the customisation
 1359 example <a class="reference external" href="customizing.html#tracking-different-types-of-issues">tracking different types of issues</a>.</li>
 1360 </ol>
 1361 </div>
 1362 <div class="section" id="platform-specific-notes">
 1363 <h2><a class="toc-backref" href="#id21">Platform-Specific Notes</a><a class="headerlink" href="#platform-specific-notes" title="Permalink to this headline"></a></h2>
 1364 <div class="section" id="windows-command-line-tools">
 1365 <h3><a class="toc-backref" href="#id22">Windows command-line tools</a><a class="headerlink" href="#windows-command-line-tools" title="Permalink to this headline"></a></h3>
 1366 <p>To make the command-line tools accessible in Windows, you need to update
 1367 the “Path” environment variable in the Registry via a dialog box.</p>
 1368 <p>On Windows 2000 and later:</p>
 1369 <ol class="arabic simple">
 1370 <li>Press the “Start” button.</li>
 1371 <li>Choose “Settings”</li>
 1372 <li>Choose “Control Panel”</li>
 1373 <li>Choose “System”</li>
 1374 <li>Choose “Advanced”</li>
 1375 <li>Choose “Environmental Variables”</li>
 1376 <li>Add: “&lt;dir&gt;Scripts” to the “Path” environmental variable.</li>
 1377 </ol>
 1378 <p>Where &lt;dir&gt; in 7) is the root directory (e.g., <code class="docutils literal"><span class="pre">C:\Python22\Scripts</span></code>)
 1379 of your Python installation.</p>
 1380 <p>I understand that in XP, 2) above is not needed as “Control
 1381 Panel” is directly accessible from “Start”.</p>
 1382 <p>I do not believe this is possible to do in previous versions of Windows.</p>
 1383 </div>
 1384 <div class="section" id="windows-server">
 1385 <h3><a class="toc-backref" href="#id23">Windows Server</a><a class="headerlink" href="#windows-server" title="Permalink to this headline"></a></h3>
 1386 <p>To have the Roundup web server start up when your machine boots up, there
 1387 are two different methods, the scheduler and installing the service.</p>
 1388 <div class="section" id="using-the-windows-scheduler">
 1389 <h4>1. Using the Windows scheduler<a class="headerlink" href="#using-the-windows-scheduler" title="Permalink to this headline"></a></h4>
 1390 <p>Set up the following in Scheduled Tasks (note, the following is for a
 1391 cygwin setup):</p>
 1392 <p><strong>Run</strong></p>
 1393 <blockquote>
 1394 <div><code class="docutils literal"><span class="pre">c:\cygwin\bin\bash.exe</span> <span class="pre">-c</span> <span class="pre">&quot;roundup-server</span> <span class="pre">TheProject=/opt/roundup/trackers/support&quot;</span></code></div></blockquote>
 1395 <p><strong>Start In</strong></p>
 1396 <blockquote>
 1397 <div><code class="docutils literal"><span class="pre">C:\cygwin\opt\roundup\bin</span></code></div></blockquote>
 1398 <p><strong>Schedule</strong></p>
 1399 <blockquote>
 1400 <div>At System Startup</div></blockquote>
 1401 <p>To have the Roundup mail gateway run periodically to poll a POP email address,
 1402 set up the following in Scheduled Tasks:</p>
 1403 <p><strong>Run</strong></p>
 1404 <blockquote>
 1405 <div><code class="docutils literal"><span class="pre">c:\cygwin\bin\bash.exe</span> <span class="pre">-c</span> <span class="pre">&quot;roundup-mailgw</span> <span class="pre">/opt/roundup/trackers/support</span> <span class="pre">pop</span> <span class="pre">roundup:roundup&#64;mail-server&quot;</span></code></div></blockquote>
 1406 <p><strong>Start In</strong></p>
 1407 <blockquote>
 1408 <div><code class="docutils literal"><span class="pre">C:\cygwin\opt\roundup\bin</span></code></div></blockquote>
 1409 <p><strong>Schedule</strong></p>
 1410 <blockquote>
 1411 <div><p>Every 10 minutes from 5:00AM for 24 hours every day</p>
 1412 <p>Stop the task if it runs for 8 minutes</p>
 1413 </div></blockquote>
 1414 </div>
 1415 <div class="section" id="installing-the-roundup-server-as-a-windows-service">
 1416 <h4>2. Installing the roundup server as a Windows service<a class="headerlink" href="#installing-the-roundup-server-as-a-windows-service" title="Permalink to this headline"></a></h4>
 1417 <p>This is more Windows oriented and will make the Roundup server run as
 1418 soon as the PC starts up without any need for a login or such. It will
 1419 also be available in the normal Windows Administrative Tools.</p>
 1420 <p>For this you need first to create a service ini file containing the
 1421 relevant settings.</p>
 1422 <ol class="arabic">
 1423 <li><p class="first">It is created if you execute the following command from within the
 1424 scripts directory (notice the use of backslashes):</p>
 1425 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">roundup</span><span class="o">-</span><span class="n">server</span> <span class="o">-</span><span class="n">S</span> <span class="o">-</span><span class="n">C</span> <span class="o">&lt;</span><span class="n">trackersdir</span><span class="o">&gt;</span>\<span class="n">server</span><span class="o">.</span><span class="n">ini</span> <span class="o">-</span><span class="n">n</span> <span class="o">&lt;</span><span class="n">servername</span><span class="o">&gt;</span> <span class="o">-</span><span class="n">p</span> <span class="mi">8080</span> <span class="o">-</span><span class="n">l</span> <span class="o">&lt;</span><span class="n">trackersdir</span><span class="o">&gt;</span>\<span class="n">trackerlog</span><span class="o">.</span><span class="n">log</span> <span class="n">software</span><span class="o">=&lt;</span><span class="n">trackersdir</span><span class="o">&gt;</span>\<span class="n">Software</span>
 1426 </pre></div>
 1427 </div>
 1428 <p>where the item <code class="docutils literal"><span class="pre">&lt;trackersdir&gt;</span></code> is replaced with the physical directory
 1429 that hosts all of your trackers. The <code class="docutils literal"><span class="pre">&lt;servername&gt;</span></code> item is the name
 1430 of your roundup server PC, such as w2003srv or similar.</p>
 1431 </li>
 1432 <li><p class="first">Next open the now created file <code class="docutils literal"><span class="pre">C:\DATA\roundup\server.ini</span></code> file
 1433 (if your <code class="docutils literal"><span class="pre">&lt;trackersdir&gt;</span></code> is <code class="docutils literal"><span class="pre">C:\DATA\roundup</span></code>).
 1434 Check the entries for correctness, especially this one:</p>
 1435 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">trackers</span><span class="p">]</span>
 1436 <span class="n">software</span> <span class="o">=</span> <span class="n">C</span><span class="p">:</span>\<span class="n">DATA</span>\<span class="n">Roundup</span>\<span class="n">Software</span>
 1437 </pre></div>
 1438 </div>
 1439 <p>(this is an example where the tracker is named software and its home is
 1440 <code class="docutils literal"><span class="pre">C:\DATA\Roundup\Software</span></code>)</p>
 1441 </li>
 1442 <li><p class="first">Next give the commands that actually installs and starts the service:</p>
 1443 <div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">roundup</span><span class="o">-</span><span class="n">server</span> <span class="o">-</span><span class="n">C</span> <span class="n">C</span><span class="p">:</span>\<span class="n">DATA</span>\<span class="n">Roundup</span>\<span class="n">server</span><span class="o">.</span><span class="n">ini</span> <span class="o">-</span><span class="n">c</span> <span class="n">install</span>
 1444 <span class="n">roundup</span><span class="o">-</span><span class="n">server</span> <span class="o">-</span><span class="n">c</span> <span class="n">start</span>
 1445 </pre></div>
 1446 </div>
 1447 </li>
 1448 <li><p class="first">Finally open the AdministrativeTools/Services applet and locate the
 1449 Roundup service entry. Open its properties and change it to start
 1450 automatically instead of manually.</p>
 1451 </li>
 1452 </ol>
 1453 <p>If you are using Apache as the webserver you might want to use it with
 1454 mod_python instead to serve out Roundup. In that case see the mod_python
 1455 instructions above for details.</p>
 1456 </div>
 1457 </div>
 1458 <div class="section" id="sendmail-smrsh">
 1459 <h3><a class="toc-backref" href="#id24">Sendmail smrsh</a><a class="headerlink" href="#sendmail-smrsh" title="Permalink to this headline"></a></h3>
 1460 <p>If you use Sendmail’s <code class="docutils literal"><span class="pre">smrsh</span></code> mechanism, you will need to tell
 1461 smrsh that roundup-mailgw is a valid/trusted mail handler
 1462 before it will work.</p>
 1463 <p>This is usually done via the following 2 steps:</p>
 1464 <ol class="arabic simple">
 1465 <li>make a symlink in <code class="docutils literal"><span class="pre">/etc/smrsh</span></code> called <code class="docutils literal"><span class="pre">roundup-mailgw</span></code>
 1466 which points to the full path of your actual <code class="docutils literal"><span class="pre">roundup-mailgw</span></code>
 1467 script.</li>
 1468 <li>change your alias to <code class="docutils literal"><span class="pre">&quot;|roundup-mailgw</span> <span class="pre">&lt;tracker_home&gt;&quot;</span></code></li>
 1469 </ol>
 1470 </div>
 1471 <div class="section" id="linux">
 1472 <h3><a class="toc-backref" href="#id25">Linux</a><a class="headerlink" href="#linux" title="Permalink to this headline"></a></h3>
 1473 <p>Make sure you read the instructions under <a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a>.</p>
 1474 </div>
 1475 <div class="section" id="solaris">
 1476 <h3><a class="toc-backref" href="#id26">Solaris</a><a class="headerlink" href="#solaris" title="Permalink to this headline"></a></h3>
 1477 <p>You’ll need to build Python.</p>
 1478 <p>Make sure you read the instructions under <a class="reference internal" href="#unix-environment-steps">UNIX environment steps</a>.</p>
 1479 </div>
 1480 </div>
 1481 <div class="section" id="problems-testing-your-python">
 1482 <h2><a class="toc-backref" href="#id27">Problems? Testing your Python…</a><a class="headerlink" href="#problems-testing-your-python" title="Permalink to this headline"></a></h2>
 1483 <div class="admonition note">
 1484 <p class="first admonition-title">Note</p>
 1485 <p>The <code class="docutils literal"><span class="pre">run_tests.py</span></code> script is packaged in Roundup’s source distribution
 1486 - users of the Windows installer, other binary distributions or
 1487 pre-installed Roundup will need to download the source to use it.</p>
 1488 <p class="last">Remember to have a database user ‘rounduptest’ prepared (with
 1489 password ‘rounduptest’). This user
 1490 must have at least the rights to create and drop databases.
 1491 Documentation: details on <a class="reference external" href="https://dev.mysql.com/doc/refman/8.0/en/creating-accounts.html">adding MySQL users</a>,
 1492 for PostgreSQL you want to call the <code class="docutils literal"><span class="pre">createuser</span></code> command with the
 1493 <code class="docutils literal"><span class="pre">-d</span></code> option to allow database creation.</p>
 1494 </div>
 1495 <p>Once you’ve unpacked roundup’s source, run <code class="docutils literal"><span class="pre">python</span> <span class="pre">run_tests.py</span></code> in the
 1496 source directory and make sure there are no errors. If there are errors,
 1497 please let us know!</p>
 1498 <p>If the above fails, you may be using the wrong version of python. Try
 1499 <code class="docutils literal"><span class="pre">python2</span> <span class="pre">run_tests.py</span></code> or <code class="docutils literal"><span class="pre">python2.7</span> <span class="pre">run_tests.py</span></code>.
 1500 If that works, you will need to substitute <code class="docutils literal"><span class="pre">python2</span></code> or <code class="docutils literal"><span class="pre">python2.7</span></code>
 1501 for <code class="docutils literal"><span class="pre">python</span></code> in all further commands you use in relation to Roundup –
 1502 from installation and scripts.</p>
 1503 </div>
 1504 </div>
 1505 
 1506 
 1507        
 1508     <div class="related related-bottom">
 1509       <ul>
 1510         <li class="right" style="margin-right: 10px">
 1511           <a href="genindex.html" title="General Index"
 1512              accesskey="I">index</a></li>
 1513         <li class="right" >
 1514           <a href="upgrading.html" title="Upgrading to newer versions of Roundup"
 1515              accesskey="N">next</a></li>
 1516         <li class="right" >
 1517           <a href="features.html" title="Roundup Features"
 1518              accesskey="P">previous</a></li>
 1519         <li><a href="index.html">Roundup 2.0.0 documentation</a></li> 
 1520       </ul>
 1521     </div>
 1522     </div>
 1523     <div class="footer">
 1524         &copy; Copyright 2009-2020, Richard Jones, Roundup-Team.
 1525     </div>
 1526   </body>
 1527 </html>