Installing Roundup

Running in Demo Mode with Docker

You can either:

• use a published container from hub.docker.com with rounduptracker/roundup:latest

and start demo mode with:

docker run --rm -p 127.0.0.1:8917:8080 --name roundup_demo -v \
   $PWD:/usr/src/app/tracker rounduptracker/roundup:latest demo

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)

and start demo mode with:

docker run --rm -p 127.0.0.1:8917:8080 --name roundup_demo -v \
   $PWD:/usr/src/app/tracker roundup-app:latest demo

This will create a demo subdirectory which is your tracker’s home. It will also print the URL for exploring your new tracker.

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.

Standard Installation

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.

Installing from downloaded source

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.

Choosing Your Template

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.

Choosing Your Backend

The actual storage of Roundup tracker information is handled by backends.

Roundup supports basic full text search (FTS) for all backends. Some backends support a faster native FTS. Also Roundup supports using whoosh or xapian for FTS.

There are several backends to choose from, each with benefits and limitations:

anydbm

This was one of the original database backends. It is a simple key/value store and is a prototype implementation for NoSQL backends. It also used to be the only backend that was guaranteed to be present. These days using SQLite is preferred unless you have some reason for preferring a key/value backend (e.g. you are interested in adding support for MongoDB or other NoSQL persistence layer).

sqlite

This uses the embedded database engine SQLite and the PySQLite driver 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 version 2.1.0 and sqlite3 (the last being bundled with Python 2.5+)

Installed SQLite should be the latest version available (3.9.0 or newer).

Installation of Roundup 2.2.0 or newer requires that the installed SQLite supports FTS5. This is required even if you are not going to use FTS5 for full text searching. FTS5 was included in SQLite release 3.9.0 in October 2015. However some vendors choose not to include it. RedHat 7’s native sqlite3 is known to not work.

You can check your SQLite by using the command line:

echo 'pragma compile_options' | sqlite3 | grep FTS5

it should output ENABLE_FTS5 if FTS5 is supported.

You can check using the same version of Python you use for running Roundup with:

import sqlite3

con = sqlite3.connect(':memory:')
cur = con.cursor()
cur.execute('pragma compile_options;')
available_pragmas = cur.fetchall()
con.close()

The output should include ('ENABLE_FTS5',) in the output.

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.

postgresql

Backend for popular RDBMS PostgreSQL. You must read doc/postgresql.txt for additional installation steps and requirements. You must also configure the rdbms section of your tracker’s config.ini. It is recommended that you use at least version 2.8 of psycopg2.

Roundup supports using postgresql’s full text search capability. This can improve searching if you are not installing another indexer like xapian or whoosh. It can be tuned to work with different languages.

mysql

Backend for popular RDBMS MySQL. You must read doc/mysql.txt for additional installation steps and requirements. You must also configure the rdbms section of your tracker’s config.ini

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.

Web Server cgi-bin

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://learn.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:

Through an environment variable

Set the variable TRACKER_HOMES to be a colon (“:”) separated list of name=home pairs (if you’re using apache, the SetEnv directive can do this)

Directly in the roundup.cgi file itself

Add your instance to the TRACKER_HOMES variable as 'name': 'home'

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>

CGI-bin for Limited-Access Hosting

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.

1. Install flup

2. 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()
   

3. 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.

Stand-alone Web Server

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.

Zope Product - ZRoundup

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.

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 for more detailed directions.

LD_PRELOAD=/lib/libpthread.so.0
export LD_PRELOAD

LD_PRELOAD=/usr/lib/libc_r.so
export LD_PRELOAD

#################################################
# 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>

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>

Nginx HTTP Server

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 customising 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;
    }
  }
}

FastCGI (Cherokee, Hiawatha, lighttpd)

The Hiawatha and lighttpd web servers can run Roundup using FastCGI. Cherokee can run FastCGI but it also supports wsgi directly using a wsgi server like 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.

WSGI Variations

python setup.py build_doc
python setup.py sdist --manifest-only
python setup.py install --home="/home/roundup/install" --force

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>

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]

# 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)

SCRIPT_NAME=/tracker gunicorn --bind 127.0.0.1:8917 --timeout=10 wsgi:app

uwsgi --http-socket 127.0.0.1:8917 \
    --plugin python3 --mount=/tracker=wsgi.py \
    --manage-script-name --callable app

As a mail alias pipe process

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.

As a custom router/transport using a pipe process (Exim4 specific)

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.

• This avoids privilege escalation, since otherwise the pipe process will run as the mail user, typically mail. The transport can be configured to run as the user appropriate for the task at hand. In the transport described in this section, Exim4 runs as the unprivileged user roundup.

• Separate configuration is not required for each tracker instance. When a email arrives at the server, Exim passes it through the defined routers. The roundup_router looks for a match with one of the roundup directories, and if there is one it is passed to the roundup_transport, which uses the pipe process described in the previous section (As a mail alias pipe process).

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.

This config makes a few assumptions:

• That the mail address corresponding to the tracker instance has the same name as the directory of the tracker instance, i.e. the mail interface address corresponding to a Roundup instance called /var/lib/roundup/trackers/mytracker is mytracker@your.host.

• That (at least) all the db subdirectories of all the tracker instances (ie. /var/lib/roundup/trackers/*/db) are owned by the same user, in this case, ‘roundup’.

• That if the schema.py file exists, then the tracker is ready for use. Another option is to use the config.ini file (this changed in 0.8 from config.py).

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

As a regular job using a mailbox source

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”.

As a regular job using a POP source

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.

apop (authenticated) and pops (pop over ssl) methods are also supported. See the section on mailgw in the admin guide.

On windows, you would set up the command using the windows scheduler.

As a regular job using an IMAP source

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 securnae connection. To use imap with CRAM or OAUTH, see the section on mailgw in the admin guide .

As with the POP job, on windows, you would set up the command using the windows scheduler.

Building a Docker Container

You can build a docker container in one of 4 modes defined by the source build-arg.

--build-arg="source=local"

the default if no source is defined. Build using the version in the source tree by running setup.py install.

--build-arg="source=pypi"

build the newest production release version deployed to pypi. If you want to build using a pre-release, you can append pip version specifiers to pypi without embedding any spaces. For example:

# install 2.2.0 if available or 2.2.0b1 or 2.2.0b2 etc.
--build-arg="source=pypi~=2.2.0b1"

# install only a 2.2.0 beta
--build-arg="source=pypi~=2.2.0b1,!=2.2.0"

Note that versions of Roundup before 2.2 may not run correctly in a Docker container.

--build-arg="source=pip_local"

Build using the version in the source tree by running pip install. This places some files (e.g. man pages, templates) in different directories from the local install but is preferred by some Python users.

--build-arg="source=pip_sdist"

Disabled - hopefully it will be available in the future. This is meant for maintainer/developer use. It installs using pip from a source distribution (sdist) tarball built by following the RELEASE.txt. It is meant for testing releases or building a docker image that installs a new pending source distribution release. Normal users/admins should not use it. Use local or pip_local instead.

Build a docker container using the code in the current directory, with this build command from the top of the source tree:

docker build -t roundup-app -f scripts/Docker/Dockerfile .

Build a container using the newest production (non pre-release) Roundup release on PyPI, by running:

docker build -t roundup-app --build-arg="source=pypi" \
     -f scripts/Docker/Dockerfile .

Change the build-arg for building in other modes.

The Dockerfile 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 adding:

--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 and GID.

Configuring Roundup in the Container

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:

• Nginx HTTP Server

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.

Running Your Container

As of version 2.3.0 the Docker container has multiple entry points.

docker run -it --rm -p 127.0.0.1:9017:8080 \
   -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest

docker run -it \
    -v $PWD/tracker:/usr/src/app/tracker \
    roundup-app:latest help

docker run -it \
    -v $PWD/tracker:/usr/src/app/tracker \
    roundup-app:latest shell

docker run -it \
    -v $PWD/tracker:/usr/src/app/tracker \
    roundup-app:latest admin -i tracker/tracker1

docker run -it \
    -v $PWD/tracker:/usr/src/app/tracker \
    roundup-app:latest admin templates

docker run -it -p 127.0.0.1:8917:8080 \
    -v $PWD/tracker:/usr/src/app/tracker \
    roundup-app:latest demo anydbm responsive

Running Multiple Trackers

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.

Docker-compose Deployment

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.

Tags for Dockerhub Docker Images

The docker images available from https://hub.docker.com/r/rounduptracker/roundup are tagged with: version-build, version, and latest tags. Only production releases (not pre-releases) are tagged this way. For example, the tags when 2.3.0 is released will be:

rounduptracker/roundup:latest

is a moving tag that tracks the latest build with the newest production version of Roundup using the current newest Alpine release with the versions of Python packages at the time of the build.

rounduptracker/roundup:2.3.0

is a moving tag that tracks the latest build of version 2.3.0 of Roundup. The Roundup software in this build will match the 2.3.0 version released on PyPi, but the underlying Alpine image or versions of the supporting Python libraries (redis, xapian, psycopg2, …) will change.

rounduptracker/roundup:2.3.0-1

is a static tag and marks the first build of the version 2.3.0 docker image. When a new release of the image is done, it will get the tag 2.3.0-2 etc. This is an alternative to pulling using a sha256 sum. However it is possible to overwrite this image/tag. So it does not provide the same security guarantees that using a sha256 sum does.

In addition to the release tags, there may be one or more development tags available. All tags will include devel. For example: rounduptracker/roundup:2.3.0b1-devel, rounduptracker/roundup:devel

You should not assume that any devel tag is static. They are mainly for use by Roundup developers/maintainers/testers for testing. There may be alternate tags ending 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.

Windows

Note: command history and editing not available

Linux

Make sure you read the instructions under UNIX environment steps.

Solaris

You’ll need to build Python.

Make sure you read the instructions under UNIX environment steps.