"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "share/doc/roundup/html/_sources/installation.txt" between
roundup-1.6.1.tar.gz and roundup-2.0.0.tar.gz

About: Roundup is an highly customisable issue-tracking system with command-line, web and e-mail interfaces (written in Python).

installation.txt  (roundup-1.6.1):installation.txt  (roundup-2.0.0)
.. index:: Installation
================== ==================
Installing Roundup Installing Roundup
================== ==================
.. contents:: .. contents::
:depth: 2 :depth: 2
:local: :local:
Overview Overview
======== ========
skipping to change at line 32 skipping to change at line 34
Roundup support code Roundup support code
Installed into your Python install's lib directory. Installed into your Python install's lib directory.
Roundup scripts Roundup scripts
These include the email gateway, the roundup These include the email gateway, the roundup
HTTP server, the roundup administration command-line interface, etc. HTTP server, the roundup administration command-line interface, etc.
Prerequisites Prerequisites
============= =============
Roundup requires Python 2.7 or newer (but not Python 3) with a functioning Roundup requires Python 2.7 or 3.4 or newer with a functioning
anydbm module. Download the latest version from https://www.python.org/. anydbm module. Download the latest version from https://www.python.org/.
It is highly recommended that users install the latest patch version It is highly recommended that users install the latest patch version
of python as these contain many fixes to serious bugs. of python as these contain many fixes to serious bugs.
Some variants of Linux will need an additional "python dev" package Some variants of Linux will need an additional "python dev" package
installed for Roundup installation to work. Debian and derivatives, are installed for Roundup installation to work. Debian and derivatives, are
known to require this. known to require this.
If you are using the Roundup Windows installer on a 64 bit system and If you are using the Roundup Windows installer on a 64 bit system and
you get the error message:: you get the error message::
skipping to change at line 66 skipping to change at line 68
Full timezone support requires pytz_ module (version 2005i or later) Full timezone support requires pytz_ module (version 2005i or later)
which brings the `Olson tz database`_ into Python. If pytz_ is not which brings the `Olson tz database`_ into Python. If pytz_ is not
installed, timezones may be specified as numeric hour offsets only. installed, timezones may be specified as numeric hour offsets only.
This is optional but strongly suggested. This is optional but strongly suggested.
An RDBMS An RDBMS
Sqlite, MySQL and Postgresql are all supported by Roundup and will be Sqlite, MySQL and Postgresql are all supported by Roundup and will be
used if available. One of these is recommended if you are anticipating a used if available. One of these is recommended if you are anticipating a
large user base (see `choosing your backend`_ below). large user base (see `choosing your backend`_ below).
.. index:: roundup-admin:: reindex subcommand
Xapian full-text indexer Xapian full-text indexer
The Xapian_ full-text indexer is also supported and will be used by The Xapian_ full-text indexer is also supported and will be used by
default if it is available. This is strongly recommended if you are default if it is available. This is strongly recommended if you are
anticipating a large number of issues (> 5000). anticipating a large number of issues (> 5000).
You may install Xapian at any time, even after a tracker has been You may install Xapian at any time, even after a tracker has been
installed and used. You will need to run the "roundup-admin reindex" installed and used. You will need to run the "roundup-admin reindex"
command if the tracker has existing data. command if the tracker has existing data.
Roundup requires Xapian 1.0.0 or newer. Roundup requires Xapian 1.0.0 or newer.
skipping to change at line 102 skipping to change at line 106
2.0 series may work. Whoosh is a pure python indexer so it is slower 2.0 series may work. Whoosh is a pure python indexer so it is slower
than Xapian, but should be useful for moderately sized trackers. than Xapian, but should be useful for moderately sized trackers.
It uses the StandardAnalyzer which is suited for Western languages. It uses the StandardAnalyzer which is suited for Western languages.
pyopenssl pyopenssl
If pyopenssl_ is installed the roundup-server can be configured If pyopenssl_ is installed the roundup-server can be configured
to serve trackers over SSL. If you are going to serve roundup via to serve trackers over SSL. If you are going to serve roundup via
proxy through a server with SSL support (e.g. apache) then this is proxy through a server with SSL support (e.g. apache) then this is
unnecessary. unnecessary.
pyme gpg
If pyme_ is installed you can configure the mail gateway to perform If gpg_ is installed you can configure the mail gateway to perform
verification or decryption of incoming OpenPGP MIME messages. When verification or decryption of incoming OpenPGP MIME messages. When
configured, you can require email to be cryptographically signed configured, you can require email to be cryptographically signed
before roundup will allow it to make modifications to issues. before roundup will allow it to make modifications to issues.
jinja2 jinja2
To use the jinja2 template (may still be experimental, check out To use the jinja2 template (may still be experimental, check out
its TEMPLATE-INFO.txt file) you need its TEMPLATE-INFO.txt file) you need
to have the jinja2_ template engine installed. to have the jinja2_ template engine installed.
pyjwt
To use jwt tokens for login (experimental), install pyjwt. If you
don't have it installed, jwt tokens are not supported.
docutils
To use ReStructuredText rendering you need to have the docutils
package installed.
markdown, markdown2 or mistune
To use markdown rendering you need to have the markdown, markdown2
or mistune package installed.
Windows Service Windows Service
You can run Roundup as a Windows service if pywin32_ is installed. You can run Roundup as a Windows service if pywin32_ is installed.
Otherwise it must be started manually. Otherwise it must be started manually.
.. _Xapian: https://xapian.org/ .. _Xapian: https://xapian.org/
.. _Whoosh: https://bitbucket.org/mchaput/whoosh/wiki/Home .. _Whoosh: https://bitbucket.org/mchaput/whoosh/wiki/Home
.. _pytz: https://pypi.org/project/pytz/ .. _pytz: https://pypi.org/project/pytz/
.. _Olson tz database: https://www.iana.org/time-zones .. _Olson tz database: https://www.iana.org/time-zones
.. _pyopenssl: http://pyopenssl.sourceforge.net .. _pyopenssl: http://pyopenssl.sourceforge.net
.. _pyme: http://pyme.sourceforge.net .. _gpg: https://www.gnupg.org/software/gpgme/index.html
.. _pywin32: https://pypi.org/project/pywin32/ .. _pywin32: https://pypi.org/project/pywin32/
.. _jinja2: http://jinja.pocoo.org/ .. _jinja2: http://jinja.pocoo.org/
.. _docutils: https://docutils.sourceforge.io/
.. _markdown: https://python-markdown.github.io/
.. _markdown2: https://github.com/trentm/python-markdown2
.. _mistune: https://github.com/lepture/mistune
Getting Roundup Getting Roundup
=============== ===============
.. note:: .. note::
Some systems, such as Debian and NetBSD, already have Roundup Some systems, such as Debian and NetBSD, already have Roundup
installed. Try running the command "roundup-admin" with no arguments, installed. Try running the command "roundup-admin" with no arguments,
and if it runs you may skip the `Basic Installation Steps`_ and if it runs you may skip the `Basic Installation Steps`_
below and go straight to `configuring your first tracker`_. below and go straight to `configuring your first tracker`_.
skipping to change at line 218 skipping to change at line 238
a. (Optional) If you intend to keep your roundup trackers a. (Optional) If you intend to keep your roundup trackers
under one top level directory which does not exist yet, under one top level directory which does not exist yet,
you should create that directory now. Example:: you should create that directory now. Example::
mkdir /opt/roundup/trackers mkdir /opt/roundup/trackers
b. Either add the Roundup script location to your ``PATH`` b. Either add the Roundup script location to your ``PATH``
environment variable or specify the full path to environment variable or specify the full path to
the command in the next step. the command in the next step.
.. index:: roundup-admin; install subcommand
c. Install a new tracker with the command ``roundup-admin install``. c. Install a new tracker with the command ``roundup-admin install``.
You will be asked a series of questions. Descriptions of the provided You will be asked a series of questions. Descriptions of the provided
templates can be found in `choosing your template`_ below. Descriptions templates can be found in `choosing your template`_ below. Descriptions
of the available backends can be found in `choosing your backend`_ of the available backends can be found in `choosing your backend`_
below. The questions will be something like (you may have more below. The questions will be something like (you may have more
templates or backends available):: templates or backends available)::
Enter tracker home: /opt/roundup/trackers/support Enter tracker home: /opt/roundup/trackers/support
Templates: classic Templates: classic
Select template [classic]: classic Select template [classic]: classic
skipping to change at line 258 skipping to change at line 280
"tracker :: web" variable to:: "tracker :: web" variable to::
web = http://localhost:8080/support/ web = http://localhost:8080/support/
The URL *must* end in a '/', or your web interface *will not work*. The URL *must* end in a '/', or your web interface *will not work*.
See `Customising Roundup`_ for details on configuration and schema See `Customising Roundup`_ for details on configuration and schema
changes. You may change any of the configuration after changes. You may change any of the configuration after
you've initialised the tracker - it's just better to have valid values you've initialised the tracker - it's just better to have valid values
for this stuff now. for this stuff now.
.. index:: roundup-admin; initialise subcommand
d. Initialise the tracker database with ``roundup-admin initialise``. d. Initialise the tracker database with ``roundup-admin initialise``.
You will need to supply an admin password at this step. You will be You will need to supply an admin password at this step. You will be
prompted:: prompted::
Admin Password: Admin Password:
Confirm: Confirm:
Note: running this command will *destroy any existing data in the Note: running this command will *destroy any existing data in the
database*. In the case of MySQL and PostgreSQL, any existing database database*. In the case of MySQL and PostgreSQL, any existing database
will be dropped and re-created. will be dropped and re-created.
skipping to change at line 314 skipping to change at line 338
set of messages which are disseminated to the issue's list of nosy users. set of messages which are disseminated to the issue's list of nosy users.
Minimal Template Minimal Template
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
The minimal template has the minimum setup required for a tracker The minimal template has the minimum setup required for a tracker
installation. That is, it has the configuration files, defines a user database installation. That is, it has the configuration files, defines a user database
and the basic HTML interface to that. It's a completely clean slate for you to and the basic HTML interface to that. It's a completely clean slate for you to
create your tracker on. create your tracker on.
.. index:: database; choosing your backend
Choosing Your Backend Choosing Your Backend
--------------------- ---------------------
The actual storage of Roundup tracker information is handled by backends. The actual storage of Roundup tracker information is handled by backends.
There's several to choose from, each with benefits and limitations: There's several to choose from, each with benefits and limitations:
========== =========== ===== ============================== ========== =========== ===== ==============================
Name Speed Users Support Name Speed Users Support
========== =========== ===== ============================== ========== =========== ===== ==============================
anydbm Slowest Few Always available anydbm Slowest Few Always available
skipping to change at line 356 skipping to change at line 382
Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional
installation steps and requirements. You must also configure the ``rdbms`` installation steps and requirements. You must also configure the ``rdbms``
section of your tracker's ``config.ini`` section of your tracker's ``config.ini``
You may defer your decision by setting your tracker up with the anydbm You may defer your decision by setting your tracker up with the anydbm
backend (which is guaranteed to be available) and switching to one of the backend (which is guaranteed to be available) and switching to one of the
other backends at any time using the instructions in the `administration other backends at any time using the instructions in the `administration
guide`_. guide`_.
Regardless of which backend you choose, Roundup will attempt to initialise Regardless of which backend you choose, Roundup will attempt to initialise
a new database for you when you run the roundup-admin "initialise" command. a new database for you when you run the "``roundup-admin initialise``" command.
In the case of MySQL and PostgreSQL you will need to have the appropriate In the case of MySQL and PostgreSQL you will need to have the appropriate
privileges to create databases. privileges to create databases.
Configure a Web Interface Configure a Web Interface
------------------------- -------------------------
There are multiple web interfaces to choose from: There are multiple web interfaces to choose from:
1. `web server cgi-bin`_ 1. `web server cgi-bin`_
2. `cgi-bin for limited-access hosting`_ 2. `cgi-bin for limited-access hosting`_
3. `stand-alone web server`_ 3. `stand-alone web server`_
4. `Zope product - ZRoundup`_ 4. `Zope product - ZRoundup`_
5. `Apache HTTP Server with mod_python`_ 5. `Apache HTTP Server with mod_wsgi`_
6. `WSGI handler`_ 6. `Apache HTTP Server with mod_python`_ (deprecated)
7. `WSGI Variations`_
You may need to give the web server user permission to access the tracker home You may need to give the web server user permission to access the tracker home
- see the `UNIX environment steps`_ for information. You may also need to - see the `UNIX environment steps`_ for information. You may also need to
configure your system in some way - see `platform-specific notes`_. configure your system in some way - see `platform-specific notes`_.
.. index:: pair: web interface; cgi
Web Server cgi-bin Web Server cgi-bin
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
A benefit of using the cgi-bin approach is that it's the easiest way to A benefit of using the cgi-bin approach is that it's the easiest way to
restrict access to your tracker to only use HTTPS. Access will be slower restrict access to your tracker to only use HTTPS. Access will be slower
than through the `stand-alone web server`_ though. than through the `stand-alone web server`_ though.
If your Python isn't installed as "python" then you'll need to edit If your Python isn't installed as "python" then you'll need to edit
the ``roundup.cgi`` script to fix the first line. the ``roundup.cgi`` script to fix the first line.
skipping to change at line 467 skipping to change at line 496
directory to contain:: directory to contain::
RewriteEngine On RewriteEngine On
RewriteBase / RewriteBase /
RewriteRule ^(.*)$ /cgi-bin/roundup_stub/$1 [L] RewriteRule ^(.*)$ /cgi-bin/roundup_stub/$1 [L]
Now loading the (sub-)domain in a browser should load the tracker web Now loading the (sub-)domain in a browser should load the tracker web
interface. If you get a "500" error then enable the "cgitb" lines in the interface. If you get a "500" error then enable the "cgitb" lines in the
stub to get some debugging information. stub to get some debugging information.
.. index:: pair: web interface; stand alone server
Stand-alone Web Server Stand-alone Web Server
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
This approach will give you faster response than cgi-bin. You may This approach will give you faster response than cgi-bin. You may
investigate using ProxyPass or similar configuration in apache to have your investigate using ProxyPass or similar configuration in apache to have your
tracker accessed through the same URL as other systems. tracker accessed through the same URL as other systems.
The stand-alone web server is started with the command ``roundup-server``. It The stand-alone web server is started with the command ``roundup-server``. It
has several options - display them with ``roundup-server -h``. has several options - display them with ``roundup-server -h``.
The tracker home configuration is similar to the cgi-bin - you may either edit The tracker home configuration is similar to the cgi-bin - you may either edit
the script to change the TRACKER_HOMES variable or you may supply the the script to change the TRACKER_HOMES variable or you may supply the
name=home values on the command-line after all the other options. name=home values on the command-line after all the other options.
To make the server run in the background, use the "-d" option, specifying the To make the server run in the background, use the "-d" option, specifying the
name of a file to write the server process id (pid) to. name of a file to write the server process id (pid) to.
.. index:: pair: web interface; Zope
Zope Product - ZRoundup Zope Product - ZRoundup
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to ZRoundup installs as a regular Zope product. Copy the ZRoundup directory to
your Products directory either in INSTANCE_HOME/Products or the Zope your Products directory either in INSTANCE_HOME/Products or the Zope
code tree lib/python/Products. code tree lib/python/Products.
When you next (re)start up Zope, you will be able to add a ZRoundup object When you next (re)start up Zope, you will be able to add a ZRoundup object
that interfaces to your new tracker. that interfaces to your new tracker.
.. index:: ! triple: web interface; apache; mod_wsgi
! single: wsgi; apache
Apache HTTP Server with mod_wsgi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is a work in progress thanks to Garth Jensen.
See the main web site for `mod_wsgi`_ which include directions for
using mod_wsgi-express which is easier if you are not used to apache
configuration. Also there is the
`main mod_wsgi <https://modwsgi.readthedocs.io/en/develop/>`_ for more
detailed directions.
Background
^^^^^^^^^^
These notes were developed on a Microsoft Azure VM running Ubuntu
18.04 LTS. The instructions below assume:
- python and roundup are already installed
- roundup is running in the system python instance (e.g. no virtual
environment)
- the tracker ``mytracker`` is installed in the ``trackers`` folder of
home directory of a user called ``admin``. Thus, the absolute path to
the tracker home directory is ``/home/admin/trackers/mytracker``.
- the server has a static public IP address of 11.11.11.101
Install mod-wsgi
^^^^^^^^^^^^^^^^
You can install/build it using the python package manager pip, or
install using the OS package manager (apt).
Pip install of mod_wsgi
'''''''''''''''''''''''
This is the tested method, and offers an easier path to get started,
but it does mean that you will need to keep up to date with any
security or other issues. If you use the packages supplied by your OS
vendor, you may get more timely updates and notifications.
The mod_wsgi docs talk about two installation methods: (1) the
so-called CMMI method or (2) with pip. The pip method also provides an
admin script called ``mod_wsgi-express`` that can start up a
standalone instance of Apache directly from the command line with an
auto generated configuration. These instructions follow the pip
method.
1. The `mod_wsgi`_ PyPi page lists prerequisites for various types of
systems. For Ubuntu, they are apache2 and apache2-dev. To see
installed apache packages, you can use ``dpkg -l | grep apache``.
If apache2 or apache2-dev are not installed, they install them
with:
- ``sudo apt update``
- ``sudo apt install apache2 apache2-dev``
2. If ``pip`` is not already installed, install it with
``sudo apt install python-pip``
If you are using python 3, use ``sudo apt-install python3-pip`` and
change references to pip in the directions to pip3.
3. ``sudo pip install mod_wsgi``. In my case, I got warnings about
the user not owning directories, but it said it completed
"successfully."
4. For testing, open port 8000 for TCP on the server. For an Azure VM,
this is done with Azure Portal under ``Networking`` > ``Add inbound port``
rule.
5. Test with ``mod_wsgi-express start-server``. This should serve
up content on localhost port 8000. You can then direct a browser on
the server itself to http://localhost:8000/ or on another machine at
the server's domain name or ip address followed by colon then 8000
(e.g. http://11.11.11.101:8000/). If successful, you should see a
Malt Whiskey image.
Package manager install of mod_wsgi
'''''''''''''''''''''''''''''''''''
On debian (which should work for Ubuntu), install apache2 with
libapache2-mod-wsgi:
- ``sudo apt update``
- ``sudo apt install apache2 libapache2-mod-wsgi``
this is the less tested method for installing mod_wsgi and may not
install mod_wsgi-express, which is used below. However there is an
example apache config included as part of `WSGI Variations`_ that can
be used to hand craft an apache config.
You should make sure that the version you install is 3.5 or newer due
to security issues in older releases.
Configure web interface via wsgi_handler
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. In the tracker's home directory create a ``wsgi.py`` file with the
following content (substituting ``/home/admin/trackers/mytracker``
with the absolute path for your tracker's home directory):
.. code:: python
from roundup.cgi.wsgi_handler import RequestDispatcher
tracker_home = '/home/admin/trackers/mytracker'
application = RequestDispatcher(tracker_home)
To run the tracker on Port 8000 as a foreground process
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Change the ``tracker.web`` url in ``config.ini`` to port 8000 at the
server domain name or ip address (e.g. http://11.11.11.101:8000/).
2. Open port 8000 for TCP on the server if you didn't already do so.
3. ``cd`` to your tracker home directory, then run
``mod_wsgi-express start-server wsgi.py``.
4. Test by directing a browser on another machine to the url you set
``tracker.web`` to in ``config.ini``.
Run tracker as background daemon
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To run the tracker on Port 80 or as a background process, you'll need
to configure a UNIX group with appropriate privileges as described in
`UNIX environment steps`_. These steps are summarized here:
1. To add a group named "mytrackergrp" run: ``sudo groupadd mytrackergrp``.
2. Add the owner of the tracker home (admin in this example) run:
``sudo usermod -a -G mytrackergrp admin``
3. Add user that runs Apache (the default on Ubuntu is www-data) run:
``sudo usermod -a -G mytrackergrp www-data``
4. Add user mail service runs as (e.g. daemon) run:
``sudo usermod -a -G mytrackergrp daemon``
5. Change group of the database in the tracker folder run:
``sudo chgrp -R mytrackergrp ~/trackers/mytracker``.
6. Make sure group can write to the database, and any new files created
in the database will be owned by the group run:
``sudo chmod -R g+sw ~/trackers/mytracker/db``
To run mod_wsgi on PORT 80
^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Change the ``tracker.web`` url in ``config.ini`` to the server url
with no port designator. E.g. http://11.11.11.101.
2. Open port 80 on the server for TCP traffic if it isn't open already.
3. Stop the system instance of Apache to make sure it isn't holding on
to port 80 run: ``sudo service apache2 stop``.
To run as a foreground process
''''''''''''''''''''''''''''''
1. From the tracker home directory, run
``sudo mod_wsgi-express start-server wsgi.py --port 80 --user admin --group m
ytrackergrp``
To run as a background process
''''''''''''''''''''''''''''''
1. From the tracker home directory, bash
``sudo mod_wsgi-express setup-server wsgi.py --port=80 --user admin --group m
ytrackergrp --server-root=/etc/mod_wsgi-express-80``
2. Then, run ``sudo /etc/mod_wsgi-express-80/apachectl start``
3. To stop, run ``sudo /etc/mod_wsgi-express-80/apachectl stop``
.. index:: triple: web interface; apache; mod_python (depricated)
Apache HTTP Server with mod_python Apache HTTP Server with mod_python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As of roundup 2.0, mod_python support is deprecated. The apache.py
file is still available, but may be limited to working for Python 2
only. Using mod_wsgi with Apache is the recommended way to deploy
roundup under apache.
`Mod_python`_ is an `Apache`_ module that embeds the Python interpreter `Mod_python`_ is an `Apache`_ module that embeds the Python interpreter
within the server. Running Roundup this way is much faster than all within the server. Running Roundup this way is much faster than all
above options and, like `web server cgi-bin`_, allows you to use HTTPS above options and, like `web server cgi-bin`_, allows you to use HTTPS
protocol. The drawback is that this setup is more complicated. protocol. The drawback is that this setup is more complicated.
The following instructions were tested on apache 2.0 with mod_python 3.1. The following instructions were tested on apache 2.0 with mod_python 3.1.
If you are using older versions, your mileage may vary. If you are using older versions, your mileage may vary.
Mod_python uses OS threads. If your apache was built without threads Mod_python uses OS threads. If your apache was built without threads
(quite commonly), you must load the threading library to run mod_python. (quite commonly), you must load the threading library to run mod_python.
skipping to change at line 622 skipping to change at line 822
``C:\DATA\roundup``. (Notice that you must use forward slashes in paths ``C:\DATA\roundup``. (Notice that you must use forward slashes in paths
inside the httpd.conf file!) inside the httpd.conf file!)
The URL for accessing these trackers then become: The URL for accessing these trackers then become:
`http://<roundupserver>/roundup/support/`` and `http://<roundupserver>/roundup/support/`` and
``http://<roundupserver>/roundup/devel/`` ``http://<roundupserver>/roundup/devel/``
Note that in order to use https connections you must set up Apache for secure Note that in order to use https connections you must set up Apache for secure
serving with SSL. serving with SSL.
WSGI Handler WSGI Variations
~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
The WSGI handler is quite simple. The following sample code shows how .. index:: triple: web interface; apache; mod_wsgi
to use it:: single: wsgi; apache
from wsgiref.simple_server import make_server Apache Alternate
^^^^^^^^^^^^^^^^
# obtain the WSGI request dispatcher This method from Thomas Arendsen Hein goes into a bit more detail and
from roundup.cgi.wsgi_handler import RequestDispatcher is designed to allow you to run multiple roundup trackers each under
tracker_home = 'demo' their own user.
app = RequestDispatcher(tracker_home)
The tracker instances are read-only to the tracker user and located
under /srv/roundup/. The (writable) data files are stored in the home
directory of the user running the tracker.
To install roundup, download and unpack a distribution tarball and run
the following as user "roundup"::
python setup.py build_doc
python setup.py sdist --manifest-only
python setup.py install --home="/home/roundup/install" --force
Create a user roundup-foo, group roundup-foo to run the tracker. Add
the following apache config to
/etc/apache2/sites-available/roundup-foo (under debian/Ubunutu, modify
as needed):
.. code:: xml
ServerAdmin webmaster@example.com
ErrorLog /var/log/apache2/error.log
LogLevel notice
DocumentRoot /var/www/
<VirtualHost *:80>
CustomLog /var/log/apache2/access.log vhost_combined
# allow access to roundup docs
Alias /doc/ /home/roundup/install/share/doc/roundup/html/
# make apache serve static assets like css rather than
# having roundup serve the files
Alias /foo/@@file/ /srv/roundup/foo/html/
# make /foo into /foo/
RedirectMatch permanent ^/(foo)$ /$1/
# start a wsgi daemon process running as user roundup-foo
# in group roundup-foo. This also changes directory to
# ~roundup-foo before it starts roundup.wsgi.
WSGIDaemonProcess roundup-foo display-name=roundup-foo user=roundup-
foo group=roundup-foo threads=25
# make tracker available at /foo and tie it into the
# wsgi script below.
WSGIScriptAlias /foo /srv/roundup/foo/roundup.wsgi
<Location /foo>
WSGIProcessGroup roundup-foo
</Location>
</VirtualHost>
The directory ~roundup-foo should have:
* a ``db`` subdirectory where messages and files will be stored
* a symbolic link called ``instance`` to /srv/roundup/foo which has
been initialized using ``roundup-admin``.
The `Apache HTTP Server with mod_wsgi`_ section above has a simple
WSGI handler. This is an enhanced version to be put into
``/srv/roundup/foo/roundup.wsgi``.
.. code:: python
import sys, os
sys.stdout = sys.stderr
enabled = True
if enabled:
# Add the directory with the roundup installation
# subdirectory to the python path.
sys.path.insert(0, '/home/roundup/install/lib/python')
# obtain the WSGI request dispatcher
from roundup.cgi.wsgi_handler import RequestDispatcher
tracker_home = os.path.join(os.getcwd(), 'instance')
application = RequestDispatcher(tracker_home)
else:
def application(environ, start_response):
status = '503 Service Unavailable'
output = 'service is down for maintenance'
response_headers = [('Content-type', 'text/plain'),
('Content-Length', str(len(output)))]
start_response(status, response_headers)
return [output]
This handler allows you to temporarily disable the tracker by setting
"enabled = False", apache will automatically detect the changed
roundup.wsgi file and reload it.
One last change is needed. In the tracker's config.ini change the db
parameter in the [main] section to be /home/roundup-foo/db. This will
put the files and messages in the db directory for the user.
.. index:: pair: web interface; gunicorn
single: wsgi; gunicorn
Gunicorn Installation
^^^^^^^^^^^^^^^^^^^^^
To run with gunicorn use pip to install gunicorn. This configuration
uses a front end web server like nginx, hiawatha, apache configured as
a reverse proxy. See your web server's documentation on how to set it
up as a reverse proxy.
The file wsgi.py should be in the current directory with the
contents::
# if roundup is not installed on the default PYTHONPATH
# set it here with:
import sys
sys.path.append('/path/to/roundup/install/directory')
# obtain the WSGI request dispatcher
from roundup.cgi.wsgi_handler import RequestDispatcher
tracker_home = '/path/to/tracker/install/directory'
app = RequestDispatcher(tracker_home)
Assuming the proxy forwards /tracker, run gunicorn as::
SCRIPT_NAME=/tracker gunicorn --bind 127.0.0.1:8917 --timeout=10 wsgi:app
this runs roundup at port 8917 on the loopback interface. You should
configure the reverse proxy to talk to 127.0.0.1 at port 8917.
.. index:: pair: web interface; uWSGI
single: wsgi; uWSGI
uWSGI Installation
^^^^^^^^^^^^^^^^^^
For a basic roundup install using uWSGI behind a front end server,
install uwsgi and the python3 (or python) plugin. Then run::
httpd = make_server('', 8917, app) uwsgi --http-socket 127.0.0.1:8917 \
httpd.serve_forever() --plugin python3 --mount=/tracker=wsgi.py \
--manage-script-name --callable app
To test the above you should create a demo tracker with ``python demo.py``. using the same wsgi.py as was used for gunicorn. If you get path not
Edit the ``config.ini`` to change the web URL to "http://localhost:8917/". found errors, check the mount option. The /tracker entry must match
the path used for the [tracker] web value in the tracker's config.ini.
Configure an Email Interface Configure an Email Interface
---------------------------- ----------------------------
If you don't want to use the email component of Roundup, then remove the If you don't want to use the email component of Roundup, then remove the
"``nosyreaction.py``" module from your tracker "``detectors``" directory. "``nosyreaction.py``" module from your tracker "``detectors``" directory.
See `platform-specific notes`_ for steps that may be needed on your system. See `platform-specific notes`_ for steps that may be needed on your system.
There are five supported ways to get emailed issues into the There are five supported ways to get emailed issues into the
skipping to change at line 1090 skipping to change at line 1428
customizing.html#tracking-different-types-of-issues customizing.html#tracking-different-types-of-issues
.. _`customising roundup`: customizing.html .. _`customising roundup`: customizing.html
.. _`upgrading document`: upgrading.html .. _`upgrading document`: upgrading.html
.. _`administration guide`: admin_guide.html .. _`administration guide`: admin_guide.html
.. _External hyperlink targets: .. _External hyperlink targets:
.. _apache: http://httpd.apache.org/ .. _apache: http://httpd.apache.org/
.. _flup: https://pypi.org/project/flup/ .. _flup: https://pypi.org/project/flup/
.. _mod_python: http://modpython.org/ .. _mod_python: http://modpython.org/
.. _mod_wsgi: https://pypi.org/project/mod-wsgi/
.. _MySQLdb: https://pypi.org/project/mysqlclient/ .. _MySQLdb: https://pypi.org/project/mysqlclient/
.. _Psycopg: http://initd.org/psycopg/ .. _Psycopg: http://initd.org/psycopg/
.. _pysqlite: https://pysqlite.org/ .. _pysqlite: https://pysqlite.org/
.. _`adding MySQL users`: .. _`adding MySQL users`:
https://dev.mysql.com/doc/refman/8.0/en/adding-users.html https://dev.mysql.com/doc/refman/8.0/en/creating-accounts.html
 End of changes. 25 change blocks. 
20 lines changed or deleted 362 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)