Maintenance
Read the Tasks section of the administration guide for information about how to perform common maintenance tasks on Roundup.
A Roundup installation is made up of several pieces.
Trackers consist of issues (be they bug reports or otherwise). Each tracker is put in its own directory (called a tracker home) and has its own:
Roundup trackers are initialised with a "template" which defines the fields usable/assignable on a per-issue basis. Descriptions of the provided templates are given in choosing your template. Usually you start with a template then modify the tracker to implement your desired workflow. One Roundup instalation can support multiple trackers with different look/feel and workflow.
If you just want to give Roundup a whirl Right Now, follow these directions to run demo.py. Demo mode starts the classic tracker without installing Roundup on your system. If you have Docker installed, you can run demo mode using docker instead.
This is also a way to spin up a development environment or even deploy a tracker for a handful of users.
You can choose different templates and backend databases using demo mode. For example replacing demo.py (or demo if you are using docker) with:
demo jinja2 anydbm
will start the tracker using the jinja2 template with the dbm database backend (rather then the default sqlite). See Choosing Your Template for a description of available templates.
(In the directions below, replace -2.2.0 with the version number of the file you downloaded. On systems that don't have a python3 program you can run python demo.py instead.)
This will set up a classic demo tracker on your machine without installing Roundup. [1] When it's done, it'll print out a URL for your web browser at so you can explore a Roundup tracker. Three users are set up:
Note the demo tracker removes the detector (nosyreaction.py) that sends email notifications. If you later convert your demo tracker to production you will need to replace the detector to send notification emails.
Once you install Roundup, you can use the roundup-demo command to install new demo trackers.
[1] | (1, 2) Demo tracker is set up to be accessed by localhost browser. If you run demo on a server host, please stop the demo (using Control-C) after it has shown the startup notice, open file demo/config.ini with your editor, change host name in the web option in section [tracker], save the file, then re-run the demo.py program. |
You can either:
or
Use steps 1-3 to install the source then
build a local docker container using:
docker build -t roundup-app -f scripts/Docker/Dockerfile .
(see Docker Support and Building a Docker Container for more details)
Start demo mode with [2]:
docker run --rm -p 127.0.0.1:8917:8080 --name roundup_demo -v \ $PWD:/usr/src/app/tracker rounduptracker/roundup:latest demo
[2] | Replace rounduptracker/roundup:latest with roundup-app:latest if you built your own docker image. |
This will create a demo subdirectory which is your tracker's home. It will also print the URL for exploring your new tracker.
Caution!
Removing 127.0.0.1: will make the tracker accessible from any host with network access to your system. However the URL's created by Roundup will still reference localhost unless you modify the web url in the tracker section of config.ini and restart the container [1].
In the docker run command we used port 8917 for Roundup. When starting Roundup, Docker may report a long error ending with: bind: address already in use. This means that port 8917 is in use. When running inside a Docker container, demo mode is unable to automatically find a free port. You have to provide an unused port to -p.
To fix this, you can change the change the port mapping provided with -p. If you do this you must set the docker PORT_8080 environment variable on the command line to match. (If Docker ever fixes https://github.com/moby/moby/issues/3778 we won't need to worry about this.)
For example:
docker run --rm -e PORT_8080=9090 -p 127.0.0.1:9090:8080 -v \ --name roundup_demo $PWD:/usr/src/app/tracker \ rounduptracker/roundup:latest demo
will run Roundup on port 9090 and Roundup will generate the correct URL.
To shut down the tracker and get your shell back, use control-c. You can remove the tracker using rm -f on the demo directory.
Roundup requires Python 2.7 or 3.6 or newer with a functioning anydbm or sqlite module. The version installed by most vendors should work if it meets the version requirements. If necessary, you can download the latest version from https://www.python.org/. It is highly recommended that users install the latest patch version of Python as these contain many fixes to serious bugs.
Some variants of Linux will need an additional "python dev" package installed for Roundup installation to work. Debian and derivatives, are known to require this.
You may optionally install and use:
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 anticipating a large number of issues (> 5000).
You may install Xapian at any time, even after a tracker has been installed and used. You will need to run the "roundup-admin reindex" command if the tracker has existing data.
Roundup requires Xapian 1.0.0 or newer.
Note that capitalization is not preserved by the Xapian search. This is required to make the porter stemmer work so that searching for silent also returns documents with the word silently. Note that the current stemming implementation is designed for English.
The Whoosh full-text indexer is also supported and will be used by default if it is available (and Xapian is not installed). This is recommended if you are anticipating a large number of issues (> 5000). It is also the only search backend that implements fuzzy search. It matches any word that has a 1 character difference from the search term.
You may install Whoosh at any time, even after a tracker has been installed and used. You will need to run the "roundup-admin reindex" command if the tracker has existing data.
Roundup was tested with Whoosh 2.5.7, but earlier versions in the 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. It uses the StandardAnalyzer which is suited for Western languages.
To get a production installation running will take 15-30 minutes. If you want to spend less than 5 minutes to test Roundup without installing it, see For The Really Impatient.
Note
Some systems, such as Gentoo and NetBSD, already have Roundup installed. Try running the command "roundup-admin -v". If it runs and reports the current version, you may skip the Standard installation below and go straight to configuring your first tracker. However it may be an old version. If so you should probably install it in a virtual environment from the Roundup web site or pypi.
If Roundup is not installed on your system, or needs to be updated, there are multiple ways to install Roundup.
There are several steps to get Roundup serving a tracker:
For information about what Roundup installs, see the What does Roundup install section in the administration guide.
Installation of Roundup using Python3 in a virtual environment is recommended. Use:
python3 -m venv /path/to/environment/roundup
Activate the Python environment (assuming a Bourne like shell) using:
. /path/to/environment/roundup/bin/activate
To install the released Roundup core code into your Python tree and Roundup scripts into /path/to/environment/roundup/usr/bin run:
python3 -m pip install roundup
If everything went well, you should now be able to run:
roundup-admin help
and see the help text.
If you want to run Roundup commands in the future without activating the virtual environment, just call the commands using the full path. For example:
/path/to/environment/roundup/usr/bin/roundup-admin
You can use the command deactivate to return to the normal Python environment. However, for now continue with configuring your first tracker.
In general you should be installing from a released Roundup version into a virtual environment.
If you are installing a current development version or are a developer or are an expert you can use the manual installation method from a source install. From the unpacked source distribution, run:
sudo python3 setup.py install
which will put the Roundup core code into your systems Python tree and the command scripts into /usr/bin
If you would like to place the Roundup scripts in a directory other than /usr/bin, then specify the preferred location with --install-scripts. For example, to install them in /opt/roundup/bin:
sudo python setup.py install --install-scripts=/opt/roundup/bin
You can also use the --prefix option to install roundup into a completely different base directory. If you choose to do this, you will have to change Python's search path (sys.path) yourself.
Make sure the roundup-admin script location is on your PATH evironment variable. This is done automatically when you activate a virtual environment. You can also specify the full path to the command in the following steps.
To create a Roundup tracker (necessary to do before you can use the software in any real fashion), you need to set up a "tracker home":
(Optional) If you intend to keep your roundup trackers under one top level directory which does not exist yet, you should create that directory now. Example:
mkdir /opt/roundup/trackers
Install a new tracker with the command roundup-admin install. You will be asked a series of questions. Descriptions of the provided templates can be found in choosing your template below. Descriptions of the available backends can be found in choosing your backend below. The questions will be something like (you may have more templates or backends available):
Enter tracker home: /opt/roundup/trackers/support Templates: minimal, jinja2, classic, responsive, devel Select template [classic]: classic Back ends: anydbm, sqlite Select backend [anydbm]: anydbm
Note: "Back ends" selection list depends on availability of third-party database modules. Standard python distribution includes anydbm and sqlite module only.
The "support" part of the tracker home can be anything you want - it is the directory where the tracker information will be stored.
You will now be directed to edit the tracker configuration and initial schema. At a minimum, you must set "tracker :: web" (that's the "web" option in the "tracker" section), "mail :: host", and "mail :: domain". You should also set "main :: admin_email" to your local admin address to get email on unusual occurances. If you get stuck, and get configuration file errors, then see the tracker configuration section of the customisation documentation.
If you just want to get set up to test things quickly (and follow the instructions in step 3 below), you can even just set the "tracker :: web" variable to:
web = http://localhost:8080/support/
The URL must end in a '/', or your web interface will not work. See Customising Roundup for details on configuration and schema changes. You may change any of the configuration after you've initialised the tracker - it's just better to have valid values for this stuff now.
Initialise the tracker database with roundup-admin initialise. You will need to supply an admin password at this step. You will be prompted:
Admin Password: Confirm:
Note: running this command will destroy any existing data in the database. In the case of MySQL and PostgreSQL, any existing database will be dropped and re-created.
Once this is done, the tracker has been created. See the note in the user_guide on how to initialise a tracker without being prompted for the password or exposing the password on the command line.
At this point, your tracker is set up, but doesn't have a nice user interface. To set that up, we need to configure a web interface and optionally configure an email interface. If you want to try your new tracker out, assuming the web setting in the [tracker] [3] section of config.ini is set to 'http://localhost:8080/support/', run:
roundup-server support=/opt/roundup/trackers/support
then direct your web browser at:
and you should see the tracker interface.
To run your tracker on some interface other than 127.0.0.1 and port 8080 (make sure you change the "tracker :: web" option to match) use:
roundup-server -p 1080 -n 0.0.0.0 support=/opt/roundup/trackers/support
to run the server at port 1080 and bind to all ip addresses on your system. Then direct your web browser to http://your_host_name:1080/support/.
[3] | The rest of the documentation uses the abbreviated form "tracker :: web" for specifying a section and setting. |
Roundup ships with 5 templates. A description of each follows. When Roundup is installed, you can also get a description of available templates using roundup-admin templates. You can use this to view additional templates that you create or download.
The classic template is the one defined in the Roundup Specification. It holds issues which have priorities and statuses. Each issue may also have a set of messages which are disseminated to the issue's list of nosy users.
The minimal template has the minimum setup required for a tracker installation. That is, it has the configuration files, defines a user database and the basic HTML interface to that. It's a completely clean slate for you to create your tracker on.
There are three other templates distributed with Roundup:
Also other people have listed their trackers for different needs at: https://wiki.roundup-tracker.org/TrackerTemplates.
The actual storage of Roundup tracker information is handled by backends. There's several to choose from, each with benefits and limitations:
Name | Speed | Users | Support |
---|---|---|---|
anydbm | Slowest | Few | Always available |
sqlite | Fastest | Few | Always available |
postgresql | Fast | Many | Needs install/admin (psycopg2) |
mysql | Fast | Many | Needs install/admin (MySQLdb) |
This uses the embedded database engine PySQLite to provide a very fast backend. This is not suitable for trackers which will have many simultaneous users, but requires much less installation and maintenance effort than more scalable postgresql and mysql backends.
SQLite is supported via PySQLite versions 1.1.7, 2.1.0 and sqlite3 (the last being bundled with Python 2.5+)
Installed SQLite should be the latest version available (3.3.8 is known to work, 3.1.3 is known to have problems).
Roundup supports using sqlite's full text search capability. This can improve searching if you are not installing another indexer like xapian or whoosh. It works best with English text.
You may defer your decision by setting your tracker up with the anydbm backend (which is guaranteed to be available) and switching to one of the other backends at any time using the instructions in the administration guide.
Regardless of which backend you choose, Roundup will attempt to initialise a new database for you when you run the "roundup-admin initialise" command. In the case of MySQL and PostgreSQL you will need to have the appropriate privileges to create databases.
There are multiple ways to deploy the web interface. If your tracker will be heavily used and accessible from the internet, we suggest using Apache or Nginx in WSGI mode or as a reverse proxy to the stand alone web server or WSGI server like Gunicorn.
A FastCGI deployment with an alternate web server is suitable for lower traffic sites.
If you already run Zope, Roundup should deploy nicely in that framework.
If you are internet accessible, but expect a few users, or are on a hosted web server, using cgi-bin is a reasonable deployment.
Using a true HTTP server provide tools including: DOS prevention, throttling, web application firewalls etc. that are worth having in an internet facing application.
If you are running on an internal intranet, you can use the stand alone server: roundup-server, but even in this environment, using a real web server to serve static files and other resources will perform better.
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 configure your system in some way - see platform-specific notes.
A benefit of using the cgi-bin approach is that it's the easiest way to restrict access to your tracker to only use HTTPS. Access will be slower than through the stand-alone web server though.
If your Python isn't installed as "python" then you'll need to edit the roundup.cgi script to fix the first line.
If you're using IIS on a Windows platform, you'll need to run this command for the cgi to work (it turns on the PATH_INFO cgi variable):
adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
The adsutil.vbs file can be found in either c:\inetpub\adminscripts or c:\winnt\system32\inetsrv\adminsamples\ or c:\winnt\system32\inetsrv\adminscripts\ depending on your installation.
See:
https://learn.microsoft.com/en-us/iis/web-dev-reference/server-variables
More information about ISS setup may be found at:
https://docs.microsoft.com/en-us/iis/
Copy the share/roundup/cgi-bin/roundup-cgi (frontends/roundup.cgi in source tree) file to your web server's cgi-bin directory. You will need to configure it to tell it where your tracker home is. You can do this either:
The "name" part of the configuration will appear in the URL and identifies the tracker (so you may have more than one tracker per cgi-bin script). Make sure there are no spaces or other illegal characters in it (to be safe, stick to letters and numbers). The "name" forms part of the URL that appears in the tracker config "tracker :: web" variable, so make sure they match. The "home" part of the configuration is the tracker home directory.
If you're using Apache, you can use an additional trick to hide the .cgi extension of the cgi script. Place the roundup.cgi script wherever you want it to be, rename it to just roundup, and add a couple lines to your Apache configuration:
<Location /path/to/roundup> SetHandler cgi-script </Location>
If you are running in a shared-hosting environment or otherwise don't have permission to edit the system web server's configuration, but can create a .htaccess file then you may be able to use this approach.
Install flup
Create a script roundup_stub in your server's cgi-bin directory containing:
#!/usr/bin/env python # if necessary modify the Python path to include the place you # installed Roundup #import sys #sys.path.append('...') # cgitb is needed for debugging in browser only #import cgitb #cgitb.enable() # obtain the WSGI request dispatcher from roundup.cgi.wsgi_handler import RequestDispatcher tracker_home = '/path/to/tracker/home' app = RequestDispatcher(tracker_home) from flup.server.cgi import WSGIServer WSGIServer(app).run()
Modify or created the .htaccess file in the desired (sub-)domain directory to contain:
RewriteEngine On RewriteBase / RewriteRule ^(.*)$ /cgi-bin/roundup_stub/$1 [L]
Now loading the (sub-)domain in a browser should load the tracker web interface. If you get a "500" error then enable the "cgitb" lines in the stub to get some debugging information.
This approach will give you faster response than cgi-bin. You may investigate using ProxyPass or similar configuration in apache to have your tracker accessed through the same URL as other systems.
The stand alone serveris used by the Docker image.
The stand-alone web server is started with the command roundup-server. It has several options - display them with roundup-server -h.
The tracker home configuration is similar to the cgi-bin - you may either edit the script to change the TRACKER_HOMES variable or you may supply the name=home values on the command-line after all the other options.
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.
ZRoundup installs as a regular Zope product. Copy the share/roundup/frontends/ZRoundup (frontends/ZRoundup in the source tree) directory to your Products directory either in INSTANCE_HOME/Products or the Zope code tree lib/python/Products.
When you next (re)start up Zope, you will be able to add a ZRoundup object that interfaces to your new tracker.
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 for more detailed directions.
These notes were developed on a Microsoft Azure VM running Ubuntu 18.04 LTS. The instructions below assume:
You can install/build it using the python package manager pip, or install using the OS package manager (apt).
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.
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:
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.
sudo pip install mod_wsgi. In my case, I got warnings about the user not owning directories, but it said it completed "successfully."
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.
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.
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.
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):
from roundup.cgi.wsgi_handler import RequestDispatcher tracker_home = '/home/admin/trackers/mytracker' application = RequestDispatcher(tracker_home)
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:
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 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 protocol. The drawback is that this setup is more complicated.
The following instructions were tested on apache 2.0 with mod_python 3.1. If you are using older versions, your mileage may vary.
Mod_python uses OS threads. If your apache was built without threads (quite commonly), you must load the threading library to run mod_python. This is done by setting LD_PRELOAD to your threading library path in apache envvars file. Example for gentoo linux (envvars file is located in /usr/lib/apache2/build/):
LD_PRELOAD=/lib/libpthread.so.0 export LD_PRELOAD
Example for FreeBSD (envvars is in /usr/local/sbin/):
LD_PRELOAD=/usr/lib/libc_r.so export LD_PRELOAD
Next, you have to add Roundup trackers configuration to apache config. Roundup apache interface uses the following options specified with PythonOption directives:
In the following example we have two trackers set up in /var/db/roundup/support and /var/db/roundup/devel and accessed as https://my.host/roundup/support/ and https://my.host/roundup/devel/ respectively (provided Apache has been set up for SSL of course). Having them share same parent directory allows us to reduce the number of configuration directives. Support tracker has russian user interface. The other tracker (devel) has english user interface (default).
Static files from html directory are served by apache itself - this is quicker and generally more robust than doing that from python. Everything else is aliased to dummy (non-existing) py file, which is handled by mod_python and our roundup module.
Example mod_python configuration:
################################################# # Roundup Issue tracker ################################################# # enable Python optimizations (like 'python -O') PythonOptimize On # let apache handle static files from 'html' directories AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2 # everything else is handled by roundup web UI AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2 # roundup requires a slash after tracker name - add it if missing RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/ # common settings for all roundup trackers <Directory /var/db/roundup/*> Order allow,deny Allow from all AllowOverride None Options None AddHandler python-program .py PythonHandler roundup.cgi.apache # uncomment the following line to see tracebacks in the browser # (note that *some* tracebacks will be displayed anyway) #PythonDebug On </Directory> # roundup tracker homes <Directory /var/db/roundup/support> PythonOption TrackerHome /var/db/roundup/support PythonOption TrackerLanguage ru </Directory> <Directory /var/db/roundup/devel> PythonOption TrackerHome /var/db/roundup/devel </Directory>
Notice that the /var/db/roundup path shown above refers to the directory in which the tracker homes are stored. The actual value will thus depend on your system.
On Windows the corresponding lines will look similar to these:
AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2 <Directory C:/DATA/roundup/*> <Directory C:/DATA/roundup/support> <Directory C:/DATA/roundup/devel>
In this example the directory hosting all of the tracker homes is C:\DATA\roundup. (Notice that you must use forward slashes in paths inside the httpd.conf file!)
The URL for accessing these trackers then become: http://<roundupserver>/roundup/support/` and http://<roundupserver>/roundup/devel/
Note that in order to use https connections you must set up Apache for secure serving with SSL.
This configuration uses Gunicorn to run Roundup behind an Nginx proxy. The proxy also compresses the data using gzip. The url for the tracker in config.ini should be https://tracker.example.org.
user nginx; worker_processes auto; worker_rlimit_nofile 10000; error_log /var/log/nginx/global-error.log; pid /var/run/nginx.pid; events { worker_connections 1024; } upstream tracker-tracker { # Gunicorn uses this socket for communication server unix:/var/run/roundup/tracker.sock fail_timeout=0; } http { include /etc/nginx/mime.types; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"'; access_log /var/log/nginx/global-access.log main; sendfile on; tcp_nopush on; tcp_nodelay on; server_tokens off; gzip_http_version 1.1; gzip_proxied any; gzip_min_length 500; # default comp_level is 1 gzip_comp_level 6; gzip_disable msie6 gzip_types text/plain text/css text/xml application/xml text/javascript application/javascript text/json application/json; # upstream proxies need to match Accept-Encoding as # part of their cache check gzip_vary on server { listen 80; server_name tracker.example.org; location /.well-known/acme-challenge/ { alias /etc/lego/.well-known/acme-challenge/; try_files $uri =404; } location / { return 301 https://$http_host$request_uri; } } server { listen 443 ssl; server_name tracker.example.org; include mime.types; # By default use the snakeoil certificate... # change this if you are using a real SSL cert ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem; ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key; # These are useful for @@files where roundup is bypassed. # but can be set by roundup as well. See: # https://wiki.roundup-tracker.org/AddingContentSecurityPolicy # which also sets other security headers. add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload"; add_header X-Frame-Options "sameorigin"; add_header X-Xss-Protection "1; mode=block"; add_header X-Content-Type-Options "nosniff"; add_header X-Permitted-Cross-Domain-Policies "none"; error_log /var/log/nginx/roundup-tracker.error.log; access_log /var/log/nginx/roundup-tracker.access.log root /home/roundup/trackers/tracker/; # have nginx return files from @@file directly rather than # going though roundup location /@@file/ { rewrite ^/@@file/(.*) /html/$1 break; # note that you can not use cache control (see customizing doc) # in roundup to set the expires headers since we are # bypassing roundup. Consider using a map or different # location stanzas to vary the expiration times. expires 1h; } location / { # must define tracker-tracker in upstream stanza proxy_pass http://tracker-tracker/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } }
The Hiawatha and lighttpd web servers can run Roundup using FastCGI. Cherokee can run FastCGI but it also supports wsgi directly using a uWSGI, Gnuicorn etc.
To run Roundup using FastCGI, the flup package can be used under Python 2 and Python 3. We don't have a detailed config for this, but the basic idea can be found at: https://flask.palletsprojects.com/en/2.0.x/deploying/fastcgi/
If you have deployed Roundup using FastCGI and flup we welcome example configuration files and instructions.
This method from Thomas Arendsen Hein goes into a bit more detail and is designed to allow you to run multiple roundup trackers each under their own user.
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):
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 initialised 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.
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.
To run with Gunicorn use pip install gunicorn. This configuration uses a front end web server like nginx, hiawatha, or 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 (obtained from frontends/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. If you want you can use a unix domain socket instead. Example: --bind unix:///var/run/roundup/tracker.sock would be used for the nginx configuration below.
For a basic roundup install using uWSGI behind a front end server, install uwsgi and the python3 (or python) plugin. Then run:
uwsgi --http-socket 127.0.0.1:8917 \ --plugin python3 --mount=/tracker=wsgi.py \ --manage-script-name --callable app
using the same wsgi.py as was used for Gunicorn. If you get path not 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.
If you don't want to use the email component of Roundup, then remove the "nosyreaction.py" module from your tracker "detectors" directory.
See platform-specific notes for steps that may be needed on your system.
There are five supported ways to get emailed issues into the Roundup tracker. You should pick ONE of the following, all of which will continue my example setup from above:
Set up a mail alias called "issue_tracker" as (include the quote marks): "|/usr/bin/python /usr/bin/roundup-mailgw <tracker_home>" (substitute /usr/bin for wherever roundup-mailgw is installed).
In some installations (e.g. RedHat Linux and Fedora Core) you'll need to set up smrsh so sendmail will accept the pipe command. In that case, symlink /etc/smrsh/roundup-mailgw to "/usr/bin/roundup-mailgw" and change the command to:
|roundup-mailgw /opt/roundup/trackers/support
To test the mail gateway on unix systems, try:
echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
Be careful that some mail systems (postfix for example) will impose limits on processes they spawn. In particular postfix can set a file size limit that is inherited by the mailgw. If the database files (anydbm, sqlite) exceed this limit, this can cause your Roundup database to become corrupted.
The following configuration snippets for Exim 4 configuration implement a custom router & transport to accomplish mail delivery to roundup-mailgw. A configuration for Exim3 is similar but not included, since Exim3 is considered obsolete.
This configuration is similar to the previous section, in that it uses a pipe process. However, there are advantages to using a custom router/transport process, if you are using Exim.
The matching is done in the line:
require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
The following configuration has been tested on Debian Sarge with Exim4.
Note
The Debian Exim4 packages don't allow pipes in alias files by default, so the method described in the section As a mail alias pipe process will not work with the default configuration. However, the method described in this section does. See the discussion in /usr/share/doc/exim4-config/README.system_aliases on any Debian system with Exim4 installed.
For more Debian-specific information, see suggested addition to README.Debian in https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283, which will hopefully be merged into the Debian package eventually.
This config makes a few assumptions:
Macros for Roundup router/transport. Should be placed in the macros section of the Exim4 config:
# Home dir for your Roundup installation ROUNDUP_HOME=/var/lib/roundup/trackers # User and group for Roundup. ROUNDUP_USER=roundup ROUNDUP_GROUP=roundup
Custom router for Roundup. This will (probably) work if placed at the beginning of the router section of the Exim4 config:
roundup_router: driver = accept # The config file config.ini seems like a more natural choice, but the # file config.py was replaced by config.ini in 0.8, and schema.py needs # to be present too. require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py transport = roundup_transport
Custom transport for Roundup. This will (probably) work if placed at the beginning of the router section of the Exim4 config:
roundup_transport: driver = pipe command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/ current_directory = ROUNDUP_HOME home_directory = ROUNDUP_HOME user = ROUNDUP_USER group = ROUNDUP_GROUP
Set roundup-mailgw up to run every 10 minutes or so. For example (substitute /usr/bin for wherever roundup-mailgw is installed):
0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
Where the mail_spool_file argument is the location of the roundup submission user's mail spool. On most systems, the spool for a user "issue_tracker" will be "/var/mail/issue_tracker".
To retrieve from a POP mailbox, use a cron entry similar to the mailbox one (substitute /usr/bin for wherever roundup-mailgw is installed):
0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
where pop_spec is "username:password@server" that specifies the roundup submission user's POP account name, password and server.
On windows, you would set up the command using the windows scheduler.
To retrieve from an IMAP mailbox, use a cron entry similar to the POP one (substitute /usr/bin for wherever roundup-mailgw is installed):
0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
where imap_spec is "username:password@server" that specifies the roundup submission user's IMAP account name, password and server. You may optionally include a mailbox to use other than the default INBOX with "imap username:password@server mailbox".
If you have a secure (ie. HTTPS) IMAP server then you may use imaps in place of imap in the command to use a secure connection.
As with the POP job, on windows, you would set up the command using the windows scheduler.
Each tracker ideally should have its own UNIX group, so create a UNIX group (edit /etc/group or your appropriate NIS map if you're using NIS). To continue with my examples so far, I would create the UNIX group 'support', although the name of the UNIX group does not have to be the same as the tracker name. To this 'support' group I then add all of the UNIX usernames who will be working with this Roundup tracker. In addition to 'real' users, the Roundup email gateway will need to have permissions to this area as well, so add the user your mail service runs as to the group (typically "mail" or "daemon"). The UNIX group might then look like:
support:*:1002:jblaine,samh,geezer,mail
If you intend to use the web interface (as most people do), you should also add the username your web server runs as to the group. My group now looks like this:
support:*:1002:jblaine,samh,geezer,mail,apache
The tracker "db" directory should be chmod'ed g+sw so that the group can write to the database, and any new files created in the database will be owned by the group.
If you're using the mysql or postgresql backend then you'll need to ensure that the tracker user has appropriate permissions to create/modify the database. If you're using roundup.cgi, the apache user needs permissions to modify the database. Alternatively, explicitly specify a database login in rdbms -> user and password in config.ini.
An alternative to the above is to create a new user who has the sole responsibility of running roundup. This user:
If you're using a Linux system (e.g. Fedora Core) with SELinux enabled, you will need to ensure that the db directory has a context that permits the web server to modify and create files. If you're using the mysql or postgresql backend you may also need to update your policy to allow the web server to access the database socket.
If you run a public tracker, you will eventually have to think about dealing with spam entered through both the web and mail interfaces.
See the section on Preventing SPAM in the customisation documentation that has a simple detector that will block lot of spam attempts.
If you don't want to install Roundup on a host, you can create a Docker container. This installs Roundup using the stand-alone web server method. This image only supports http. We suggest putting an https terminating proxy in front of it.
This is a work in progress and patches to improve it are welcome. You can find the docker config files under the scripts/Docker directory of the source tree.
The dockerized Roundup is based on a 64 bit Alpine distribution. It includes database drivers for anydbm, sqlite, MySQL and Postgresql (Postgresl is untested). It also includes additional libraries that are listed in scripts/Docker/requirements.txt (including redis).
Email support is a work in progress. Outgoing email to an external SMTP server should work. Receiving email should work by using a scheduled (cron) job to access email:
However running cron in a container is problematic (running busybox crond as root vs. non-root, requiring setgrp privs etc). Patches for implementing email support are welcome.
If you want to use a MySQL backend, the docker-compose.yml file will deploy a Roundup container and a MySQL container backend for use with Roundup.
We recommend you follow the OSWAP Docker Security practices for your production Roundup instance.
To build a docker container using the code in the current directory, run this build command from the top of the source tree:
docker build -t roundup-app -f scripts/Docker/Dockerfile .
You can also build a container using the newest Roundup release on PyPI, by running:
docker build -t roundup-app --build-arg="source=pypi" \ -f scripts/Docker/Dockerfile .
The docker declares a single volume mounted at /usr/src/app/tracker inside the container. You will mount your tracker home directory at this location. The /usr/src/app path can be changed by using --build-arg="appdir=/new/path".
You can also add additional modules to the docker container by using --build-arg="pip_mod=requests setproctitle".
Because of deficiencies in the docker program (see: https://github.com/moby/moby/issues/29110#issuecomment-1100676306), there is no way to determine the version of Python inside the container and make that available as part of the build process. If your build fails because the pythonversion does not match, add the suggested --build-arg to the docker build command line.
By default the container runs Roundup using UID 1000. By setting --build-arg="roundup_uid=2000" you can change the UID.
Caution!
Docker modifies iptables firewall rules. This allows access to the container from your local network. See the official documentation for details. UFW rules are known to be be ignored (see: https://github.com/moby/moby/issues/4737). Use -p 127.0.0.1:ext_port:container_port in your docker run commands or implement suggestions like: https://github.com/chaifeng/ufw-docker.
Once the docker image is created using one of the build commands above, run an interactive session with:
docker run -it --rm -p 127.0.0.1:9017:8080 \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
The -v option maps a directory from the host into the docker container. Note that uid 1000 is used by roundup by default. The uid of the directory (and all files under it) must match the uid. You can set the UID at image build time. This example assumes your tracker configs are in the tracker subdirectory. Replace $PWD/tracker with the full path name to the directory where the tracker home(s) are to be stored.
The -p option maps an external port (9017) to proxy the roundup server running at port 8080 to the outside. Note if you remove 127.0.0.1: from the -p argument, any host on the network will be able to access the tracker at port 9017.
If the tracker directory is empty, the docker container will prompt you to install a tracker template (step 3) and prompt you for the database type.
Then you need to configure the tracker by editing template/config.ini. Make sure that the tracker web setting ends in /issues/ See Configuring your first tracker and the top of config.ini for other settings.
Once you have configured the tracker, run another interactive session to initialise the tracker (step 4) with:
docker run -it --rm -p 127.0.0.1:9017:8080 \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
this will initialise the database and attempt to start the server. If that is successful, use control-c to exit the server.
Now start the server non-interactively (note no -it option) with:
docker run -p 9017:8080 -d \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
Your tracker will be available at: http://yourhost:9017/issues/.
If you need to access your container while the server is running you can use:
docker exec -it c0d5 sh
where c0d5 is the id prefix for the running container obtained from docker container ls.
You should place a web server in front of Roundup (in reverse proxy mode) for production use. See the proxy_pass example below:
You can expose the port directly to your intranet by removing 127.0.0.1 from the -p option. See Stand-alone Web Server for more details.
Note
The examples below use the locally built docker container specification: roundup-app. You can replace it with the docker hub specification rounduptracker/roundup:latest (provided latest is newer than 2.3.0).
As of version 2.3.0 the Docker container has multiple entry points.
By default, running:
docker run -it --rm -p 127.0.0.1:9017:8080 \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
3 times will install, initialize and serve a Roundup tracker at ..../issues/ using $PWD/tracker as the tracker home. This is the "guided install" method described in Configuring Roundup in the Container.
Once you have initialized your tracker, any arguments placed at the end of the docker run command are passed to the roundup-server. These arguments replace the default arguments of issues=tracker.
You can invoke a shell inside the container without exec'ing into the container using:
docker run -it \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest shell
Then you can manually configure your tracker using roundup-admin -i tracker using the directions for Configuring your first tracker. This is also how you would access tools like roundup-gettext which do not have direct entry points like admin for roundup-admin and demo for roundup-demo.
You can run roundup-admin directly by using:
docker run -it \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest admin -i tracker/tracker1
to start roundup-admin using the directory $PWD/tracker/tracker1. This is one way to create multiple trackers in subdirectories. It is no different from starting a shell and invoking roundup-admin manually.
One possibly useful command is:
docker run -it \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest admin templates
to list description of all the installed templates.
Lastly you can:
docker run -it -p 127.0.0.1:8917:8080 \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest demo anydbm responsive
to create a directory $PWD/tracker/demo and autoconfigure a server using the anydbm backend based on the responsive tracker template. See demo mode using docker for steps to change the server port.
If you add -e SHELL_DEBUG=1 to the docker command, it sets the SHELL_DEBUG environment variable which will enable debugging output from the startup script.
If you want to run multiple trackers, create a subdirectory for each tracker home under the volume mount point ($PWD/tracker). Then invoke docker run passing the roundup-server tracker specifications like:
docker run --rm -p 9017:8080 \ -v /.../issue.tracker:/usr/src/app/tracker \ roundup-app:latest tracker1=tracker/tracker1_home \ tracker2=tracker/tracker2_home
This will set up two trackers that can be reached at http://yourhost:9017/tracker1/ and http://yourhost:9017/tracker2/. The arguments after roundup-app:latest are arguments including tracker paths that are passed to roundup-server.
If you want to run using the mysql backend, you can use docker-compose with scripts/Docker/docker-compose.yml. This will run Roundup and MySQL in containers. Directions for building using docker-compose are at the top of the yml file.
The docker images available from https://hub.docker.com/r/rounduptracker/roundup are tagged with: version-build, version, and latest tags. For example, the tags when 2.3.0 is released will be:
In addition to the release tags, there may be one or more development tags available. All tags will start with devel. For example: rounduptracker/roundup:devel.
You should not assume that any devel tag is static. They ae mainly for use by Roundup developer/maintainer for testing. There may be alternate tags starting with devel- to indicate builds from specific Mercurial versions/hashes. Also the tag may be overwritten to change the underlying Python libraries or images. Unless you like the bleeding edge, these should not be used in production.
Read the Tasks section of the administration guide for information about how to perform common maintenance tasks on Roundup.
Read the separate upgrading document, which describes the steps needed to upgrade existing tracker trackers for each version of Roundup that is released.
If you intend to use Roundup with anything other than the default templates, if you would like to hack on Roundup, or if you would like implementation details, you should read Customising Roundup.
Things to think about before you jump off the deep end and install multiple trackers, which involve additional URLs, user databases, email addresses, databases to back up, etc.
To make the command-line tools accessible in Windows, you need to update the "Path" environment variable in the Registry via a dialog box.
On Windows 2000 and later:
Where <dir> in 7) is the root directory (e.g., C:\Python27\Scripts) of your Python installation.
I understand that in XP, 2) above is not needed as "Control Panel" is directly accessible from "Start".
I do not believe this is possible to do in previous versions of Windows.
To have the Roundup web server start up when your machine boots up, there are two different methods, the scheduler and installing the service.
Set up the following in Scheduled Tasks (note, the following is for a cygwin setup):
To have the Roundup mail gateway run periodically to poll a POP email address, set up the following in Scheduled Tasks:
Every 10 minutes from 5:00AM for 24 hours every day
Stop the task if it runs for 8 minutes
This is more Windows oriented and will make the Roundup server run as soon as the PC starts up without any need for a login or such. It will also be available in the normal Windows Administrative Tools.
For this you need first to create a service ini file containing the relevant settings.
It is created if you execute the following command from within the scripts directory (notice the use of backslashes):
roundup-server -S -C <trackersdir>\server.ini -n <servername> -p 8080 -l <trackersdir>\trackerlog.log software=<trackersdir>\Software
where the item <trackersdir> is replaced with the physical directory that hosts all of your trackers. The <servername> item is the name of your roundup server PC, such as w2003srv or similar.
Next open the now created file C:\DATA\roundup\server.ini file (if your <trackersdir> is C:\DATA\roundup). Check the entries for correctness, especially this one:
[trackers] software = C:\DATA\Roundup\Software
(this is an example where the tracker is named software and its home is C:\DATA\Roundup\Software)
Next give the commands that actually installs and starts the service:
roundup-server -C C:\DATA\Roundup\server.ini -c install roundup-server -c start
Finally open the AdministrativeTools/Services applet and locate the Roundup service entry. Open its properties and change it to start automatically instead of manually.
If you are using Apache as the webserver you might want to use it with mod_python instead to serve out Roundup. In that case see the mod_python instructions above for details.
If you use Sendmail's smrsh mechanism, you will need to tell smrsh that roundup-mailgw is a valid/trusted mail handler before it will work.
This is usually done via the following 2 steps:
Make sure you read the instructions under UNIX environment steps.
You'll need to build Python.
Make sure you read the instructions under UNIX environment steps.
Note
The run_tests.py script is not packaged in Roundup's source distribution anymore. You should install pytest using your distributions package manger or using pip/pip2/pip3 to install pytest for your python version. See the administration guide for details.
Remember to have a database user 'rounduptest' prepared (with password 'rounduptest'). This user must have at least the rights to create and drop databases. Documentation: details on adding MySQL users, for PostgreSQL you want to call the createuser command with the -d option to allow database creation.
This can only be done if you downloaded and unpacked the source distrbution. It will not work if you used pip install as the test suite is not installed. Once you've unpacked roundup's source, if you have pytest installed, run python -m pytest test in the source directory and make sure there are no errors. If there are errors, please let us know!