"Fossies" - the Fresh Open Source Software Archive

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


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "installation.txt": 1.6.1_vs_2.0.0.

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