Mercurial > p > roundup > code

annotate doc/installation.txt @ 8060:f53fd57a0cf3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: update link to docker publish command.
author John Rouillard <rouilj@ieee.org>
date Sun, 07 Jul 2024 10:57:31 -0400
parents 7df143a5c90b
children a4cb4e75d4e9
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6581
diff changeset
1 .. meta::
6774
e7b4ad2c57ac landmarks, skiplink, remove bad attrs, autocomplete search
John Rouillard <rouilj@ieee.org>
parents: 6769
diff changeset
2 :description:
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6581
diff changeset
3 Everything about installing the Roundup issue tracker web and
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6581
diff changeset
4 mail interfaces and configuring a tracker. How to download and
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6581
diff changeset
5 demonstrate Roundup using using command line or
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6581
diff changeset
6 Docker. Optional software that adds functionality to Roundup.
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6581
diff changeset
7
6168
de9d602c8ce6 more index entries and CHANGES.txt update for them.
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
8 .. index:: Installation
de9d602c8ce6 more index entries and CHANGES.txt update for them.
John Rouillard <rouilj@ieee.org>
parents: 6163
diff changeset
9
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
10 ==================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 Installing Roundup
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 ==================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
14 .. contents::
6555
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
15 :depth: 3
4890
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4792
diff changeset
16 :local:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 Overview
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 ========
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
22 A Roundup installation is made up of several pieces.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
23
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
24 Roundup scripts
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
25 These include the Roundup HTTP server, email gateway, administration
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
26 command-line interface, demo installer etc. These are usually placed
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
27 in a directory that is on your path.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
28
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
29 Roundup core code
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
30 Is installed into your Python's lib directory. We recommend
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
31 using a virtual environment for your Roundup installation.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
33 Roundup trackers
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
34 Trackers consist of issues (be they bug reports or otherwise). Each tracker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
35 is put in its own directory (called a tracker home) and has its own:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
36
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
37 * configuration files,
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
38 * HTML (web) files,
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
39 * database,
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
40 * logic files (detectors, schema, ...)
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
41
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
42 Roundup trackers are initialised with a "template" which defines the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
43 fields usable/assignable on a per-issue basis. Descriptions of the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
44 provided templates are given in `choosing your template`_. Usually
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
45 you start with a template then modify the tracker to implement your
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
46 desired workflow. One Roundup instalation can support multiple
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
47 trackers with different look/feel and workflow.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48
7137
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
49 For The Really Impatient
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
50 ========================
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
51
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
52 If you just want to give Roundup a whirl **Right Now**, follow these
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
53 directions to run ``demo.py``. Demo mode starts the `classic tracker`_
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
54 without installing Roundup on your system. If you have Docker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
55 installed, you can run `demo mode using docker`_ instead.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
56
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
57 This is also a way to spin up a development environment or even
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
58 deploy a tracker for a handful of users.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
59
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
60 You can choose different templates and backend databases using demo
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
61 mode. For example replacing ``demo.py`` (or ``demo`` if you are using
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
62 docker) with::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
63
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
64 demo jinja2 anydbm
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
65
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
66 will start the tracker using the jinja2 template with the dbm database
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
67 backend (rather then the default sqlite). See `Choosing Your
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
68 Template`_ for a description of available templates.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
69
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
70 (In the directions below, replace ``-2.2.0`` with the version number
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
71 of the file you downloaded. On systems that don't have a ``python3``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
72 program you can run ``python demo.py`` instead.)
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
73
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
74 .. _install the source:
7137
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
75
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
76 1. ``python3 -m pip download roundup``
8054
7df143a5c90b docs: add link to security.txt release tarball verification.
John Rouillard <rouilj@ieee.org>
parents: 7969
diff changeset
77
7df143a5c90b docs: add link to security.txt release tarball verification.
John Rouillard <rouilj@ieee.org>
parents: 7969
diff changeset
78 * (If you are really impatient, you probably don't want to
7df143a5c90b docs: add link to security.txt release tarball verification.
John Rouillard <rouilj@ieee.org>
parents: 7969
diff changeset
79 `verify the downloaded file <security.html#verify-source-tarball>`_.)
7df143a5c90b docs: add link to security.txt release tarball verification.
John Rouillard <rouilj@ieee.org>
parents: 7969
diff changeset
80
7137
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
81 2. ``tar -xzvf roundup-2.2.0.tar.gz``
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
82
7610
cc4f2a1d271c docs: replace ' with " in windows tarfile examples
John Rouillard <rouilj@ieee.org>
parents: 7609
diff changeset
83 * if you don't have a tar command, ``python3 -c "import tarfile, sys; tarfile.open(sys.argv[1]).extractall();" roundup-2.2.0.tar.gz`` can be used.
7137
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
84
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
85 3. ``cd roundup-2.2.0``
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
86 4. ``python3 demo.py``
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
87
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
88 This will set up a classic demo tracker on your machine without
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
89 installing Roundup. [1]_ When it's done, it'll print out a URL for
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
90 your web browser at so you can explore a Roundup tracker. Three users
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
91 are set up:
7137
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
92
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
93 1. anonymous - the "default" user with permission to do very little
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
94 2. demo (password "demo") - a normal user who may create issues
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
95 3. admin (password "admin") - an administrative user who has complete
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
96 access to the tracker
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
97
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
98 Note the demo tracker removes the detector (nosyreaction.py) that
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
99 sends email notifications. If you later convert your demo tracker to
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
100 production you will need to replace the detector to send notification
7137
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
101 emails.
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
102
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
103 Once you install Roundup, you can use the ``roundup-demo`` command to
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
104 install new demo trackers.
7137
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
105
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
106 .. [1] Demo tracker is set up to be accessed by localhost browser.
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
107 If you run demo on a server host, please stop the demo (using
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
108 Control-C) after it has shown the startup notice, open file
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
109 ``demo/config.ini`` with your editor, change host name in
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
110 the ``web`` option in section ``[tracker]``, save the file,
4553614a2b22 move For ... Impatient section up, add directions, style footnote
John Rouillard <rouilj@ieee.org>
parents: 7136
diff changeset
111 then re-run the demo.py program.
1218
4c9882cb16a3 more docco work
Richard Jones <richard@users.sourceforge.net>
parents: 1170
diff changeset
112
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
113 .. _demo mode using docker:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
114
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
115 Running in Demo Mode with Docker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
116 --------------------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
117
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
118 You can either:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
119
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
120 * use a published container from hub.docker.com with
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
121 ``rounduptracker/roundup:latest``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
122
7453
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
123 and start demo mode with::
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
124
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
125 docker run --rm -p 127.0.0.1:8917:8080 --name roundup_demo -v \
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
126 $PWD:/usr/src/app/tracker rounduptracker/roundup:latest demo
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
127
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
128 or
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
129
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
130 * Use steps 1-3 to `install the source`_ then
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
131
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
132 * build a local docker container using::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
133
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
134 docker build -t roundup-app -f scripts/Docker/Dockerfile .
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
135
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
136 (see `Docker Support`_ and `Building a Docker Container`_ for more
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
137 details)
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
138
7453
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
139 and start demo mode with::
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
140
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
141 docker run --rm -p 127.0.0.1:8917:8080 --name roundup_demo -v \
7453
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
142 $PWD:/usr/src/app/tracker roundup-app:latest demo
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
143
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
144 This will create a ``demo`` subdirectory which is your tracker's
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
145 home. It will also print the URL for exploring your new tracker.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
146
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
147 .. caution::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
148 Removing ``127.0.0.1:`` will make the tracker accessible from any
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
149 host with network access to your system. However the URL's created by
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
150 Roundup will still reference ``localhost`` unless you modify the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
151 ``web`` url in the ``tracker`` section of ``config.ini`` and restart
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
152 the container [1]_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
153
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
154 In the docker run command we used port 8917 for Roundup. When starting
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
155 Roundup, Docker may report a long error ending with: `bind: address
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
156 already in use.` This means that port 8917 is in use. When running
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
157 inside a Docker container, demo mode is unable to automatically find a
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
158 free port. You have to provide an unused port to ``-p``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
159
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
160 To fix this, you can change the change the port mapping provided
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
161 with ``-p``. If you do this you **must** set the docker PORT_8080
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
162 environment variable on the command line to match. (If Docker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
163 ever fixes https://github.com/moby/moby/issues/3778 we won't need
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
164 to worry about this.)
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
165
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
166 For example::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
167
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
168 docker run --rm -e PORT_8080=9090 -p 127.0.0.1:9090:8080 -v \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
169 --name roundup_demo $PWD:/usr/src/app/tracker \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
170 rounduptracker/roundup:latest demo
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
171
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
172 will run Roundup on port 9090 and Roundup will generate the correct
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
173 URL.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
174
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
175 To shut down the tracker and get your shell back, use control-c. You
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
176 can remove the tracker using ``rm -f`` on the ``demo`` directory.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
177
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 Prerequisites
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 =============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180
7438
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
181 Roundup requires Python 2.7 [3]_ or 3.6 or newer with a functioning anydbm
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
182 or sqlite module. The version installed by most vendors should work if
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
183 it meets the version requirements. If necessary, you can download the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
184 latest version from https://www.python.org/. It is highly recommended
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
185 that users install the latest patch version of Python as these contain
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
186 many fixes to serious bugs.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187
7521
763807c584ed Use double backquotes not single.
John Rouillard <rouilj@ieee.org>
parents: 7520
diff changeset
188 Some variants of Linux will need an additional '``python-dev``' package
3421
0d9406d14186 MySQL now creates String columns using the TEXT column type
Richard Jones <richard@users.sourceforge.net>
parents: 3417
diff changeset
189 installed for Roundup installation to work. Debian and derivatives, are
0d9406d14186 MySQL now creates String columns using the TEXT column type
Richard Jones <richard@users.sourceforge.net>
parents: 3417
diff changeset
190 known to require this.
0d9406d14186 MySQL now creates String columns using the TEXT column type
Richard Jones <richard@users.sourceforge.net>
parents: 3417
diff changeset
191
3296
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
192 Optional Components
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
193 ===================
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
194
3297
8f7dc283bfa5 some more Xapian stuff (doc, test fixes)
Richard Jones <richard@users.sourceforge.net>
parents: 3296
diff changeset
195 You may optionally install and use:
3296
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
196
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
197 An RDBMS
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
198 Sqlite, MySQL and Postgresql are all supported by Roundup and will be
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
199 used if available. One of these is recommended if you are anticipating a
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
200 large user base (see `choosing your backend`_ below). Sqlite should
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
201 always be available.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
202
3623
bef78d81b79c added optional prerequisite: pytz
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3571
diff changeset
203 Timezone Definitions
3731
e6ef9abfe403 fix pytz requirement version and download URL for latest package
Richard Jones <richard@users.sourceforge.net>
parents: 3730
diff changeset
204 Full timezone support requires pytz_ module (version 2005i or later)
3730
8e3b881060b4 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3729
diff changeset
205 which brings the `Olson tz database`_ into Python. If pytz_ is not
8e3b881060b4 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3729
diff changeset
206 installed, timezones may be specified as numeric hour offsets only.
5140
7ea6bbf4286c update docs for windows installer: 32 bit version of python, must run nstaller as administrator, ned pywin32 to run as service. Encourage installation of pytz.
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
207 This is optional but strongly suggested.
5321
4566360871dc Raises python requirement to 2.7.
Bernhard Reiter <bernhard@intevation.de>
parents: 5300
diff changeset
208
3296
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
209 Xapian full-text indexer
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
210 The Xapian_ full-text indexer is also supported and will be used by
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
211 default if it is available. This is strongly recommended if you are
3417
07c696890f55 mailgw subject parsing has configurable levels of strictness
Richard Jones <richard@users.sourceforge.net>
parents: 3405
diff changeset
212 anticipating a large number of issues (> 5000).
3296
d5fa5a0b5216 some minimalist docs for Xapian
Richard Jones <richard@users.sourceforge.net>
parents: 3153
diff changeset
213
3297
8f7dc283bfa5 some more Xapian stuff (doc, test fixes)
Richard Jones <richard@users.sourceforge.net>
parents: 3296
diff changeset
214 You may install Xapian at any time, even after a tracker has been
8f7dc283bfa5 some more Xapian stuff (doc, test fixes)
Richard Jones <richard@users.sourceforge.net>
parents: 3296
diff changeset
215 installed and used. You will need to run the "roundup-admin reindex"
8f7dc283bfa5 some more Xapian stuff (doc, test fixes)
Richard Jones <richard@users.sourceforge.net>
parents: 3296
diff changeset
216 command if the tracker has existing data.
8f7dc283bfa5 some more Xapian stuff (doc, test fixes)
Richard Jones <richard@users.sourceforge.net>
parents: 3296
diff changeset
217
4378
477f2a47cbca - Indexer Xapian, made Xapian 1.2 compatible.
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4355
diff changeset
218 Roundup requires Xapian 1.0.0 or newer.
3485
8d55b5db6365 xapian works, if you poke it enough
Richard Jones <richard@users.sourceforge.net>
parents: 3447
diff changeset
219
5108
67fad01d2009 issue2550653: xapian search, stemming is not working
John Rouillard <rouilj@ieee.org>
parents: 5096
diff changeset
220 Note that capitalization is not preserved by the Xapian search.
67fad01d2009 issue2550653: xapian search, stemming is not working
John Rouillard <rouilj@ieee.org>
parents: 5096
diff changeset
221 This is required to make the porter stemmer work so that searching
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
222 for ``silent`` also returns documents with the word ``silently``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
223 Note that the current stemming implementation is designed for English.
5108
67fad01d2009 issue2550653: xapian search, stemming is not working
John Rouillard <rouilj@ieee.org>
parents: 5096
diff changeset
224
5096
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
225 Whoosh full-text indexer
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
226 The Whoosh_ full-text indexer is also supported and will be used by
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
227 default if it is available (and Xapian is not installed). This is
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
228 recommended if you are anticipating a large number of issues (> 5000).
6576
c55d56ab9ee9 Document whoosh implements fuzzy search.
John Rouillard <rouilj@ieee.org>
parents: 6555
diff changeset
229 It is also the only search backend that implements fuzzy search. It
c55d56ab9ee9 Document whoosh implements fuzzy search.
John Rouillard <rouilj@ieee.org>
parents: 6555
diff changeset
230 matches any word that has a 1 character difference from the search term.
5096
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
231
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
232 You may install Whoosh at any time, even after a tracker has been
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
233 installed and used. You will need to run the "roundup-admin reindex"
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
234 command if the tracker has existing data.
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
235
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
236 Roundup was tested with Whoosh 2.5.7, but earlier versions in the
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
237 2.0 series may work. Whoosh is a pure Python indexer so it is slower
5096
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
238 than Xapian, but should be useful for moderately sized trackers.
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
239 It uses the StandardAnalyzer which is suited for Western languages.
e74c3611b138 - issue2550636, issue2550909: Added support for Whoosh indexer.
John Rouillard <rouilj@ieee.org>
parents: 5083
diff changeset
240
3885
d4163100f4f3 add pyopenssl to optional components
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
241 pyopenssl
d4163100f4f3 add pyopenssl to optional components
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
242 If pyopenssl_ is installed the roundup-server can be configured
d4163100f4f3 add pyopenssl to optional components
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
243 to serve trackers over SSL. If you are going to serve roundup via
d4163100f4f3 add pyopenssl to optional components
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
244 proxy through a server with SSL support (e.g. apache) then this is
d4163100f4f3 add pyopenssl to optional components
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
245 unnecessary.
d4163100f4f3 add pyopenssl to optional components
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3830
diff changeset
246
5494
b7fa56ced601 use gpg module instead of pyme module for PGP encryption
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5486
diff changeset
247 gpg
b7fa56ced601 use gpg module instead of pyme module for PGP encryption
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5486
diff changeset
248 If gpg_ is installed you can configure the mail gateway to perform
3922
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3885
diff changeset
249 verification or decryption of incoming OpenPGP MIME messages. When
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3885
diff changeset
250 configured, you can require email to be cryptographically signed
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3885
diff changeset
251 before roundup will allow it to make modifications to issues.
586679a314f7 role checking for PGP mail and docs
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3885
diff changeset
252
5013
c1443d96ac94 jinja2: optional requirement added to installation.txt and link to wiki page.
Bernhard Reiter <bernhard@intevation.de>
parents: 4949
diff changeset
253 jinja2
c1443d96ac94 jinja2: optional requirement added to installation.txt and link to wiki page.
Bernhard Reiter <bernhard@intevation.de>
parents: 4949
diff changeset
254 To use the jinja2 template (may still be experimental, check out
c1443d96ac94 jinja2: optional requirement added to installation.txt and link to wiki page.
Bernhard Reiter <bernhard@intevation.de>
parents: 4949
diff changeset
255 its TEMPLATE-INFO.txt file) you need
c1443d96ac94 jinja2: optional requirement added to installation.txt and link to wiki page.
Bernhard Reiter <bernhard@intevation.de>
parents: 4949
diff changeset
256 to have the jinja2_ template engine installed.
c1443d96ac94 jinja2: optional requirement added to installation.txt and link to wiki page.
Bernhard Reiter <bernhard@intevation.de>
parents: 4949
diff changeset
257
7863
bd126f890279 doc: add reference markers for markdown and docutils install.
John Rouillard <rouilj@ieee.org>
parents: 7724
diff changeset
258 .. _install/docutils:
bd126f890279 doc: add reference markers for markdown and docutils install.
John Rouillard <rouilj@ieee.org>
parents: 7724
diff changeset
259
6097
90a1470edbea added markdown rendering support using either markdown2 or markdown
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5940
diff changeset
260 docutils
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
261 To use ReStructuredText rendering you need to have the `docutils`_
6097
90a1470edbea added markdown rendering support using either markdown2 or markdown
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5940
diff changeset
262 package installed.
90a1470edbea added markdown rendering support using either markdown2 or markdown
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5940
diff changeset
263
7863
bd126f890279 doc: add reference markers for markdown and docutils install.
John Rouillard <rouilj@ieee.org>
parents: 7724
diff changeset
264 .. _install/markdown:
bd126f890279 doc: add reference markers for markdown and docutils install.
John Rouillard <rouilj@ieee.org>
parents: 7724
diff changeset
265
6099
55c56ceacb8e escape HTML tags in markdown content
Christof Meerwald <cmeerw@cmeerw.org>
parents: 6097
diff changeset
266 markdown, markdown2 or mistune
7969
ebcda75b7adb doc: clarify use of markdown and library versions.
John Rouillard <rouilj@ieee.org>
parents: 7921
diff changeset
267 To use markdown rendering (as supplied by the jinja2 template)
ebcda75b7adb doc: clarify use of markdown and library versions.
John Rouillard <rouilj@ieee.org>
parents: 7921
diff changeset
268 you need to have the markdown_,
ebcda75b7adb doc: clarify use of markdown and library versions.
John Rouillard <rouilj@ieee.org>
parents: 7921
diff changeset
269 markdown2_ (2.4.9 known to be broken, 2.3.3, 2.4.10+ known to
ebcda75b7adb doc: clarify use of markdown and library versions.
John Rouillard <rouilj@ieee.org>
parents: 7921
diff changeset
270 work), or mistune_ (v0.8.4 tested; python3 only) package installed.
6097
90a1470edbea added markdown rendering support using either markdown2 or markdown
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5940
diff changeset
271
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
272 zstd, brotli
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
273 To have roundup compress the returned data using one of these
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
274 algorithms, you can install one or more of zstd_ or brotli_.
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
275 Roundup's responses can always be compressed with gzip from the
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
276 Python standard library. Also nginx and various wsgi server can
7453
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
277 compress the response from Roundup as they transmit/proxy it to the
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
278 client.
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
279
6814
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
280 redis
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
281 Storing ephemeral data: session keys, CSRF tokens etc. can be
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
282 performance bottleneck. You can choose to deploy a Redis_ database
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
283 using the redis-py_ pypi package. See the section on
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
284 `Using Redis for Session Databases`_ in the `administration
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
285 guide`_ for details.
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
286
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
287 pyjwt
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
288 To use JWT (JSON web tokens) for login (experimental), install `pyjwt`_
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
289 (v1.7.1, v2.0.1 tested). If you don't have it installed, JWT's
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
290 are not supported.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
291
7609
044dea25c1e2 docs: mention pywin32 in label
John Rouillard <rouilj@ieee.org>
parents: 7608
diff changeset
292 pywin32 - Windows Service
4686
4e740f02e165 Remove pywin32 installation dependency by porting portalocker.py to ctypes.
anatoly techtonik <techtonik@gmail.com>
parents: 4672
diff changeset
293 You can run Roundup as a Windows service if pywin32_ is installed.
5140
7ea6bbf4286c update docs for windows installer: 32 bit version of python, must run nstaller as administrator, ned pywin32 to run as service. Encourage installation of pytz.
John Rouillard <rouilj@ieee.org>
parents: 5138
diff changeset
294 Otherwise it must be started manually.
4686
4e740f02e165 Remove pywin32 installation dependency by porting portalocker.py to ctypes.
anatoly techtonik <techtonik@gmail.com>
parents: 4672
diff changeset
295
7608
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
296 pyreadline3
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
297 When running roundup-admin on windows, installing pyreadline3_ will
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
298 allow history and editing on the command line.
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
299
7065
48da482d7d93 reference requests library for imap_oauth in roundup-mailgw
John Rouillard <rouilj@ieee.org>
parents: 7042
diff changeset
300 requests
48da482d7d93 reference requests library for imap_oauth in roundup-mailgw
John Rouillard <rouilj@ieee.org>
parents: 7042
diff changeset
301 If you are using OAuth authentication with the roundup-mailgw
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
302 mail gateway you must install the requests_ library.
7065
48da482d7d93 reference requests library for imap_oauth in roundup-mailgw
John Rouillard <rouilj@ieee.org>
parents: 7042
diff changeset
303
6814
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
304 .. _Using Redis for Session Databases:
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
305 admin_guide.html#using-redis-for-session-databases
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
306
7438
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
307 .. [3] Do not use Python 2 for new installs. The continuous
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
308 integration and other services used for developing Roundup
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
309 are dropping support for Python 2. Also optional packages
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
310 are dropping Python 2 support. As a result Python 2 may
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
311 not be supported for many more release cycles.
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
312
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
313 Installing Roundup
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
314 ==================
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
315
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
316 To get a production installation running will take 15-30 minutes. If
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
317 you want to spend less than 5 minutes to test Roundup without
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
318 installing it, see `For The Really Impatient`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
319
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
320 .. note:: Some systems, such as Gentoo and NetBSD, already have
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
321 Roundup installed. Try running the command "roundup-admin
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
322 -v". If it runs and reports the current version, you may
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
323 skip the `Standard installation`_ below and go straight to
7301
d5442d781a09 update doc on check for pre-installed roundup
John Rouillard <rouilj@ieee.org>
parents: 7137
diff changeset
324 `configuring your first tracker`_. However it may be an old
d5442d781a09 update doc on check for pre-installed roundup
John Rouillard <rouilj@ieee.org>
parents: 7137
diff changeset
325 version. If so you should probably install it in a virtual
d5442d781a09 update doc on check for pre-installed roundup
John Rouillard <rouilj@ieee.org>
parents: 7137
diff changeset
326 environment from the Roundup web site or pypi.
2742
8ac87d4092e2 more install doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 2741
diff changeset
327
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
328 If Roundup is not installed on your system, or needs to be updated,
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
329 there are multiple ways to install Roundup.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
330
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
331 * `Standard installation`_ using pip in a Virtual Environment is the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
332 recommended standard.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
333 * `Installing from downloaded source`_ allows more control over how
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
334 things are installed (including overwriting a vendor install). But
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
335 it also increases complexity as well.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
336 * Use a prebuilt docker container from
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
337 ``rounduptracker/roundup:latest`` and follow the steps in
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
338 `Running Your Container`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
339 * Install in a docker container by downloading the source
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
340 and following the steps in `Docker Support`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
341
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
342 There are several steps to get Roundup serving a tracker:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
343
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
344 1. Install using one of the methods listed above.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
345 2. Configure your tracker following `configuring your first tracker`_
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
346 for all install methods.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
347 3. Optionally `configure a web interface`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
348 4. Optionally `configure an email interface`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
349 5. Follow `UNIX environment steps`_ to restrict local access to
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
350 Roundup if you're installing on a shared UNIX system.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
351
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
352 For information about what Roundup installs, see the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
353 `What does Roundup install`_ section in the `administration guide`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
354
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
355
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
356 Standard Installation
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
357 ----------------------
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
358
6739
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6738
diff changeset
359 Installation of Roundup using Python3 in a virtual environment is
7303
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
360 recommended. Use::
6739
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6738
diff changeset
361
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6738
diff changeset
362 python3 -m venv /path/to/environment/roundup
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6738
diff changeset
363
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
364 Activate the Python environment (assuming a Bourne like shell)
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
365 using::
6739
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6738
diff changeset
366
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6738
diff changeset
367 . /path/to/environment/roundup/bin/activate
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6738
diff changeset
368
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
369 To install the released Roundup core code into your Python tree and
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
370 Roundup scripts into ``/path/to/environment/roundup/usr/bin`` run::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
371
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
372 python3 -m pip install roundup
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
373
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
374 If everything went well, you should now be able to run::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
375
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
376 roundup-admin help
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
377
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
378 and see the help text.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
379
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
380 If you want to run Roundup commands in the future without
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
381 activating the virtual environment, just call the commands using the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
382 full path. For example::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
383
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
384 /path/to/environment/roundup/usr/bin/roundup-admin
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
385
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
386 You can use the command ``deactivate`` to return to the normal
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
387 Python environment. However, for now continue with
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
388 `configuring your first tracker`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
389
7374
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
390 .. _downloaded and unpacked the source:
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
391
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
392 Installing from downloaded source
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
393 ---------------------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
394
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
395 In general you should be installing from a released Roundup version
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
396 into a virtual environment.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
397
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
398 .. _current development version: ../code.html
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
399
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
400 If you are installing a `current development version`_ or are a
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
401 developer or are an expert you can use the manual installation method
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
402 from a source install. From the unpacked source distribution, run::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
403
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
404 sudo python3 setup.py install
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
405
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
406 which will put the Roundup core code into your systems Python tree and
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
407 the command scripts into ``/usr/bin``
1590
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
408
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
409 If you would like to place the Roundup scripts in a directory other
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
410 than ``/usr/bin``, then specify the preferred location with
3949
29dfb873b32e Small documentation cleanup
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3935
diff changeset
411 ``--install-scripts``. For example, to install them in
1590
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
412 ``/opt/roundup/bin``::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
414 sudo python setup.py install --install-scripts=/opt/roundup/bin
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
415
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
416 You can also use the ``--prefix`` option to install roundup into a
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
417 completely different base directory. If you choose to do this, you
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
418 will have to change Python's search path (sys.path) yourself.
1590
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
419
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
420 Configuring your first tracker
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
421 ==============================
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
422
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
423 Make sure the ``roundup-admin`` script location is on your ``PATH``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
424 evironment variable. This is done automatically when you activate a
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
425 virtual environment. You can also specify the full path to the command
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
426 in the following steps.
1590
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
427
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
428 1. To create a Roundup tracker (necessary to do before you can
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
429 use the software in any real fashion), you need to set up a "tracker
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
430 home":
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
431
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
432 a. (Optional) If you intend to keep your roundup trackers
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
433 under one top level directory which does not exist yet,
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
434 you should create that directory now. Example::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
435
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
436 mkdir /opt/roundup/trackers
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
437
6174
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6168
diff changeset
438 .. index:: roundup-admin; install subcommand
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6168
diff changeset
439
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
440 b. Install a new tracker with the command ``roundup-admin install``.
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
441 You will be asked a series of questions. Descriptions of the provided
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
442 templates can be found in `choosing your template`_ below. Descriptions
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
443 of the available backends can be found in `choosing your backend`_
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
444 below. The questions will be something like (you may have more
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
445 templates or backends available)::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
446
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
447 Enter tracker home: /opt/roundup/trackers/support
6766
c27fc7f499c7 Update install with all current templates and mandatory backends.
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
448 Templates: minimal, jinja2, classic, responsive, devel
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449 Select template [classic]: classic
6766
c27fc7f499c7 Update install with all current templates and mandatory backends.
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
450 Back ends: anydbm, sqlite
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
451 Select backend [anydbm]: anydbm
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
452
2818
2317e43609cb remove bsddb; suggest using sqlite better than metakit
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2742
diff changeset
453 Note: "Back ends" selection list depends on availability of
2317e43609cb remove bsddb; suggest using sqlite better than metakit
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2742
diff changeset
454 third-party database modules. Standard python distribution
6766
c27fc7f499c7 Update install with all current templates and mandatory backends.
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
455 includes anydbm and sqlite module only.
2818
2317e43609cb remove bsddb; suggest using sqlite better than metakit
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2742
diff changeset
456
7303
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
457 The "support" part of the tracker home can be anything you want - it
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
458 is the directory where the tracker information will be stored.
1571
8b5ff6ca0674 more doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 1560
diff changeset
459
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
460 You will now be directed to edit the tracker configuration and
7303
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
461 initial schema. At a minimum, you must set "tracker :: web"
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
462 (that's the "web" option in the "tracker" section),
6989
b5f8b85351a9 clarify required config.ini installation changes vs optional.
John Rouillard <rouilj@ieee.org>
parents: 6988
diff changeset
463 "mail :: host", and "mail :: domain". You should also
7303
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
464 set "main :: admin_email" to your local admin address to get email
6989
b5f8b85351a9 clarify required config.ini installation changes vs optional.
John Rouillard <rouilj@ieee.org>
parents: 6988
diff changeset
465 on unusual occurances. If you get stuck,
3303
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
466 and get configuration file errors, then see the `tracker
7354
692242b3effd initial pass to change references to reference doc where needed.
John Rouillard <rouilj@ieee.org>
parents: 7350
diff changeset
467 configuration`_ section of the `reference documentation`_.
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
468
1574
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
469 If you just want to get set up to test things quickly (and follow
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
470 the instructions in step 3 below), you can even just set the
3303
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
471 "tracker :: web" variable to::
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
472
3303
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
473 web = http://localhost:8080/support/
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
474
1310
ff7b08d9ceb5 more URL trailing-/ requirements
Richard Jones <richard@users.sourceforge.net>
parents: 1300
diff changeset
475 The URL *must* end in a '/', or your web interface *will not work*.
7354
692242b3effd initial pass to change references to reference doc where needed.
John Rouillard <rouilj@ieee.org>
parents: 7350
diff changeset
476 See the `Roundup reference`_ for details on configuration and schema
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2401
diff changeset
477 changes. You may change any of the configuration after
1310
ff7b08d9ceb5 more URL trailing-/ requirements
Richard Jones <richard@users.sourceforge.net>
parents: 1300
diff changeset
478 you've initialised the tracker - it's just better to have valid values
ff7b08d9ceb5 more URL trailing-/ requirements
Richard Jones <richard@users.sourceforge.net>
parents: 1300
diff changeset
479 for this stuff now.
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
480
6174
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6168
diff changeset
481 .. index:: roundup-admin; initialise subcommand
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6168
diff changeset
482
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
483 c. Initialise the tracker database with ``roundup-admin initialise``.
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
484 You will need to supply an admin password at this step. You will be
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
485 prompted::
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
486
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
487 Admin Password:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
488 Confirm:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489
7719
3071db43bfb6 feat: issue2550852 - support using a specified PostgreSQL db schema
John Rouillard <rouilj@ieee.org>
parents: 7712
diff changeset
490 Note: running this command will *destroy any existing data in
3071db43bfb6 feat: issue2550852 - support using a specified PostgreSQL db schema
John Rouillard <rouilj@ieee.org>
parents: 7712
diff changeset
491 the database*. In the case of MySQL and PostgreSQL, any existing
3071db43bfb6 feat: issue2550852 - support using a specified PostgreSQL db schema
John Rouillard <rouilj@ieee.org>
parents: 7712
diff changeset
492 database (or optionally database schema for PostgreSQL) will be
3071db43bfb6 feat: issue2550852 - support using a specified PostgreSQL db schema
John Rouillard <rouilj@ieee.org>
parents: 7712
diff changeset
493 dropped and re-created.
2401
a405124c3847 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
494
4792
1a0cf0345465 issue2550789 document how to initialize a tracker without exposing the admin password
John Rouillard <rouilj@ieee.org>
parents: 4688
diff changeset
495 Once this is done, the tracker has been created. See the note in
7453
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
496 the `administration guide`_ on how to :ref:`initialise a
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
497 tracker without being prompted for the password <initpw>` or
feb970243b97 Clarify docker run commands and link to admin manual section
John Rouillard <rouilj@ieee.org>
parents: 7441
diff changeset
498 exposing the password on the command line.
738
7e093cbaaa98 split instance initialisation into two steps...
Richard Jones <richard@users.sourceforge.net>
parents: 729
diff changeset
499
1590
198dbefc1d5a more installation doc cleanups
Richard Jones <richard@users.sourceforge.net>
parents: 1588
diff changeset
500 2. At this point, your tracker is set up, but doesn't have a nice user
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
501 interface. To set that up, we need to `configure a web interface`_ and
1316
dd43853684d4 don't undersell the roundup-server
Richard Jones <richard@users.sourceforge.net>
parents: 1310
diff changeset
502 optionally `configure an email interface`_. If you want to try your
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
503 new tracker out, assuming the ``web`` setting in the
7438
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
504 ``[tracker]`` [4]_ section of config.ini is set to
1316
dd43853684d4 don't undersell the roundup-server
Richard Jones <richard@users.sourceforge.net>
parents: 1310
diff changeset
505 ``'http://localhost:8080/support/'``, run::
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
506
1574
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
507 roundup-server support=/opt/roundup/trackers/support
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
508
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
509 then direct your web browser at:
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
510
1845
3c6dd167a744 Fix typo in server address [SF#822967].
Johannes Gijsbers <jlgijsbers@users.sourceforge.net>
parents: 1839
diff changeset
511 http://localhost:8080/support/
1244
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
512
8dd4f736370b merge from maintenance branch
Richard Jones <richard@users.sourceforge.net>
parents: 1240
diff changeset
513 and you should see the tracker interface.
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
514
5138
c54720396f40 issue2550882. Reported by Karl-Philipp Richter. Fixed
John Rouillard <rouilj@ieee.org>
parents: 5108
diff changeset
515 To run your tracker on some interface other than 127.0.0.1 and port
7303
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
516 8080 (make sure you change the "tracker :: web" option to match) use::
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
517
5138
c54720396f40 issue2550882. Reported by Karl-Philipp Richter. Fixed
John Rouillard <rouilj@ieee.org>
parents: 5108
diff changeset
518 roundup-server -p 1080 -n 0.0.0.0 support=/opt/roundup/trackers/support
c54720396f40 issue2550882. Reported by Karl-Philipp Richter. Fixed
John Rouillard <rouilj@ieee.org>
parents: 5108
diff changeset
519
c54720396f40 issue2550882. Reported by Karl-Philipp Richter. Fixed
John Rouillard <rouilj@ieee.org>
parents: 5108
diff changeset
520 to run the server at port 1080 and bind to all ip addresses on your system.
7303
9bd9d06e2f2c Misc doc fixes.
John Rouillard <rouilj@ieee.org>
parents: 7302
diff changeset
521 Then direct your web browser to ``http://your_host_name:1080/support/``.
5321
4566360871dc Raises python requirement to 2.7.
Bernhard Reiter <bernhard@intevation.de>
parents: 5300
diff changeset
522
7438
116ea5ce06ab issue2551269: Add warning abut Python 2 support lifetime
John Rouillard <rouilj@ieee.org>
parents: 7399
diff changeset
523 .. [4] The rest of the documentation uses the abbreviated form "tracker ::
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
524 web" for specifying a section and setting.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
525
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
526 Choosing Your Template
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
527 ----------------------
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
528
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
529 Roundup ships with 5 templates. A description of each follows. When
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
530 Roundup is installed, you can also get a description of available
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
531 templates using ``roundup-admin templates``. You can use this to view
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
532 additional templates that you create or download.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
533
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
534 .. _classic tracker:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
535
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
536 Classic Template
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
537 ~~~~~~~~~~~~~~~~
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
538
7302
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
539 The classic template is the one defined in the `Roundup
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
540 Specification`_. It holds issues which have priorities and
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
541 statuses. Each issue may also have a set of messages which are
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
542 disseminated to the issue's list of nosy users.
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
543
1227
92d8e1aad2e9 added mention of the new "minimal" template...
Richard Jones <richard@users.sourceforge.net>
parents: 1221
diff changeset
544 Minimal Template
92d8e1aad2e9 added mention of the new "minimal" template...
Richard Jones <richard@users.sourceforge.net>
parents: 1221
diff changeset
545 ~~~~~~~~~~~~~~~~
92d8e1aad2e9 added mention of the new "minimal" template...
Richard Jones <richard@users.sourceforge.net>
parents: 1221
diff changeset
546
92d8e1aad2e9 added mention of the new "minimal" template...
Richard Jones <richard@users.sourceforge.net>
parents: 1221
diff changeset
547 The minimal template has the minimum setup required for a tracker
7302
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
548 installation. That is, it has the configuration files, defines a user
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
549 database and the basic HTML interface to that. It's a completely clean
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
550 slate for you to create your tracker on.
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
551
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
552 Other Templates
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
553 ~~~~~~~~~~~~~~~
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
554
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
555 There are three other templates distributed with Roundup:
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
556
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
557 devel
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
558 This is a generic issue tracker that may be used to track bugs,
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
559 feature requests, project issues or any number of other types of
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
560 issues. Most users of Roundup will find that this template suits
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
561 them, with perhaps a few customisations.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
562
7302
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
563 responsive
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
564 This issue tracker uses the same schema as devel. The difference
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
565 between devel and responsive templates is the use of Twitter
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
566 bootstrap (https://github.com/twbs/bootstrap) in templates and
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
567 HTML5 markup. Make sure the "static_files" setting in your
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
568 config.ini of your instance is set to the directory where the
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
569 static files live (the subdirectory "static" in the default of the
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
570 template).
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
571
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
572 jinja2
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
573 This is a generic issue tracker based on classic schema. It uses
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
574 Jinja2 for templating and Twitter bootstrap for responsive markup.
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
575 You will need jinja and gettext for this to work. See the wiki
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
576 page https://wiki.roundup-tracker.org/Jinja2 for updates
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
577 between releases.
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
578
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
579 Also other people have listed their trackers for different needs at:
d2633821fe07 update doc on supplied templates
John Rouillard <rouilj@ieee.org>
parents: 7301
diff changeset
580 https://wiki.roundup-tracker.org/TrackerTemplates.
1227
92d8e1aad2e9 added mention of the new "minimal" template...
Richard Jones <richard@users.sourceforge.net>
parents: 1221
diff changeset
581
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
582 .. index:: database; choosing your backend
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
583
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
584 Choosing Your Backend
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
585 ---------------------
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
586
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
587 The actual storage of Roundup tracker information is handled by backends.
7523
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
588
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
589 Roundup supports basic full text search (FTS) for all backends. Some
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
590 backends support a faster native FTS. Also Roundup supports using
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
591 whoosh or xapian for FTS.
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
592
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
593 There are several backends to choose from, each with benefits and
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
594 limitations:
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
595
2179
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
596 ========== =========== ===== ==============================
7523
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
597 Name Speed Users Support
2179
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
598 ========== =========== ===== ==============================
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
599 anydbm Slowest Few Always available
7316
a5f948e0eef5 remove (*) marker from sqlite backend table. No idea what it means.
John Rouillard <rouilj@ieee.org>
parents: 7311
diff changeset
600 sqlite Fastest Few Always available
6663
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
601 postgresql Fast Many Needs install/admin (psycopg2_)
2179
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
602 mysql Fast Many Needs install/admin (MySQLdb_)
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
603 ========== =========== ===== ==============================
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
604
7522
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
605 **anydbm**
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
606 This was one of the original database backends. It is a simple
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
607 key/value store and is a prototype implementation for NoSQL
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
608 backends. It also used to be the only backend that was
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
609 guaranteed to be present. These days using SQLite is preferred
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
610 unless you have some reason for preferring a key/value backend
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
611 (e.g. you are interested in adding support for MongoDB or other
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
612 NoSQL persistence layer).
3728
b476fef16ccc fixed support for pysqlite2 (version 2.1.0 is the minimum version supported)
Richard Jones <richard@users.sourceforge.net>
parents: 3722
diff changeset
613 **sqlite**
7522
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
614 This uses the embedded database engine SQLite and the PySQLite_
bbcdc7c92787 Add blurb for anydbm backend; clarify workding for SQLite backend.
John Rouillard <rouilj@ieee.org>
parents: 7521
diff changeset
615 driver to provide a very fast
3935
1dab48842cbd Throwing up hands in resignation and finally deleting the metakit backend.
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
616 backend. This is not suitable for trackers which will have many
1dab48842cbd Throwing up hands in resignation and finally deleting the metakit backend.
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
617 simultaneous users, but requires much less installation and maintenance
1dab48842cbd Throwing up hands in resignation and finally deleting the metakit backend.
Richard Jones <richard@users.sourceforge.net>
parents: 3922
diff changeset
618 effort than more scalable postgresql and mysql backends.
3728
b476fef16ccc fixed support for pysqlite2 (version 2.1.0 is the minimum version supported)
Richard Jones <richard@users.sourceforge.net>
parents: 3722
diff changeset
619
7921
e3975f679bf1 issue2551302 - Remove support for sqlite version 1 from back_sqlite.py
John Rouillard <rouilj@ieee.org>
parents: 7887
diff changeset
620 SQLite is supported via PySQLite version 2.1.0 and sqlite3 (the last
3728
b476fef16ccc fixed support for pysqlite2 (version 2.1.0 is the minimum version supported)
Richard Jones <richard@users.sourceforge.net>
parents: 3722
diff changeset
621 being bundled with Python 2.5+)
3794
f5ddd1639a15 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
622
7724
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
623 Installed SQLite should be the latest version available (3.9.0 or newer).
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
624
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
625 .. _fts5-testing:
6588
91ab3e0ffcd0 Summary: Add test cases for sqlite fts
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
626
7698
4e37a7833708 doc: add FTS5 requirement for sqlite backend.
John Rouillard <rouilj@ieee.org>
parents: 7659
diff changeset
627 Installation of Roundup 2.2.0 or newer requires that the installed
7724
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
628 SQLite supports FTS5. This is required even if you are not going to
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
629 use FTS5 for full text searching. FTS5 was included in SQLite
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
630 release 3.9.0 in October 2015. However some vendors choose not to
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
631 include it. RedHat 7's native sqlite3 is known to not work.
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
632
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
633 You can check your SQLite by using the command line::
7698
4e37a7833708 doc: add FTS5 requirement for sqlite backend.
John Rouillard <rouilj@ieee.org>
parents: 7659
diff changeset
634
4e37a7833708 doc: add FTS5 requirement for sqlite backend.
John Rouillard <rouilj@ieee.org>
parents: 7659
diff changeset
635 echo 'pragma compile_options' | sqlite3 | grep FTS5
4e37a7833708 doc: add FTS5 requirement for sqlite backend.
John Rouillard <rouilj@ieee.org>
parents: 7659
diff changeset
636
4e37a7833708 doc: add FTS5 requirement for sqlite backend.
John Rouillard <rouilj@ieee.org>
parents: 7659
diff changeset
637 it should output ``ENABLE_FTS5`` if FTS5 is supported.
4e37a7833708 doc: add FTS5 requirement for sqlite backend.
John Rouillard <rouilj@ieee.org>
parents: 7659
diff changeset
638
7724
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
639 You can check using the same version of Python you use for running
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
640 Roundup with::
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
641
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
642 import sqlite3
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
643
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
644 con = sqlite3.connect(':memory:')
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
645 cur = con.cursor()
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
646 cur.execute('pragma compile_options;')
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
647 available_pragmas = cur.fetchall()
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
648 con.close()
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
649
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
650 The output should include ``('ENABLE_FTS5',)`` in the output.
68c04cc8edf7 More doc upates for FTS5 requires for sqlite and roundup > 2.1.0.
John Rouillard <rouilj@ieee.org>
parents: 7719
diff changeset
651
7523
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
652 Roundup supports using `SQLite's full text search capability
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
653 <admin_guide.html#sqlite-details>`_. This
6588
91ab3e0ffcd0 Summary: Add test cases for sqlite fts
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
654 can improve searching if you are not installing another indexer like
91ab3e0ffcd0 Summary: Add test cases for sqlite fts
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
655 xapian or whoosh. It works best with English text.
2179
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
656 **postgresql**
6663
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
657 Backend for popular RDBMS PostgreSQL. You must read
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
658 `doc/postgresql.txt`_ for additional installation steps and
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
659 requirements. You must also configure
3666
8304a1c1cc98 encourage use of latest psycopg
Richard Jones <richard@users.sourceforge.net>
parents: 3647
diff changeset
660 the ``rdbms`` section of your tracker's ``config.ini``. It is recommended
6663
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
661 that you use at least version 2.8 of psycopg2.
7523
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
662
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
663 Roundup supports using `postgresql's full text search
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
664 capability
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
665 <admin_guide.html#postgresql-info>`_. This
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
666 can improve searching if you are not installing another indexer like
f2c588128202 Clarify support for basic FTS all backends; augment native FTS desc.
John Rouillard <rouilj@ieee.org>
parents: 7522
diff changeset
667 xapian or whoosh. It can be tuned to work with different languages.
1507
3481507d6098 Advertising mysql
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1317
diff changeset
668 **mysql**
6663
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
669 Backend for popular RDBMS MySQL. You must read `doc/mysql.txt`_ for
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
670 additional installation steps and requirements. You must also
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
671 configure the ``rdbms`` section of your tracker's ``config.ini``
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
672
2179
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
673 You may defer your decision by setting your tracker up with the anydbm
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
674 backend (which is guaranteed to be available) and switching to one of the
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
675 other backends at any time using the instructions in the `administration
5aa74f9879ac rework the backend selection bit
Richard Jones <richard@users.sourceforge.net>
parents: 2161
diff changeset
676 guide`_.
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
677
2401
a405124c3847 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
678 Regardless of which backend you choose, Roundup will attempt to initialise
6174
5522c950a2e4 Add indexing for roundup-admin references.
John Rouillard <rouilj@ieee.org>
parents: 6168
diff changeset
679 a new database for you when you run the "``roundup-admin initialise``" command.
2401
a405124c3847 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
680 In the case of MySQL and PostgreSQL you will need to have the appropriate
a405124c3847 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
681 privileges to create databases.
a405124c3847 doc fixes
Richard Jones <richard@users.sourceforge.net>
parents: 2258
diff changeset
682
1221
778297033003 cleanup of install docco
Richard Jones <richard@users.sourceforge.net>
parents: 1218
diff changeset
683
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
684 Configure a Web Interface
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
685 =========================
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
686
7310
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
687 There are multiple ways to deploy the web interface. If your
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
688 tracker will be heavily used and accessible from the internet, we
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
689 suggest using Apache or Nginx in WSGI mode or as a reverse proxy
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
690 to the stand alone web server or WSGI server like Gunicorn.
7310
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
691
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
692 A FastCGI deployment with an alternate web server is suitable for
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
693 lower traffic sites.
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
694
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
695 If you already run Zope, Roundup should deploy nicely in that
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
696 framework.
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
697
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
698 If you are internet accessible, but expect a few users, or are on
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
699 a hosted web server, using cgi-bin is a reasonable deployment.
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
700
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
701 Using a true HTTP server provide tools including: DOS prevention,
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
702 throttling, web application firewalls etc. that are worth having
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
703 in an internet facing application.
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
704
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
705 If you are running on an internal intranet, you can use the
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
706 stand alone server: roundup-server, but even in this environment,
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
707 using a real web server to serve static files and other resources
ac6403bfcb1f add guidance onchoosing web deployment method
John Rouillard <rouilj@ieee.org>
parents: 7303
diff changeset
708 will perform better.
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
709
6555
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
710 .. contents::
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
711 :depth: 1
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
712 :local:
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
713
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
714 You may need to give the web server user permission to access the tracker home
1939
1303c208419d some updates that were sitting on disk
Richard Jones <richard@users.sourceforge.net>
parents: 1913
diff changeset
715 - see the `UNIX environment steps`_ for information. You may also need to
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
716 configure your system in some way - see `platform-specific notes`_.
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
717
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
718 .. index:: pair: web interface; cgi
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
719
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
720 Web Server cgi-bin
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
721 ------------------
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
722
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
723 A benefit of using the cgi-bin approach is that it's the easiest way to
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
724 restrict access to your tracker to only use HTTPS. Access will be slower
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
725 than through the `stand-alone web server`_ though.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
726
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
727 If your Python isn't installed as "python" then you'll need to edit
1748
0f2678eeeac6 cgi-bin install note
Richard Jones <richard@users.sourceforge.net>
parents: 1747
diff changeset
728 the ``roundup.cgi`` script to fix the first line.
0f2678eeeac6 cgi-bin install note
Richard Jones <richard@users.sourceforge.net>
parents: 1747
diff changeset
729
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
730 .. index:: windows; IIS cgi installation
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
731
1540
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
732 If you're using IIS on a Windows platform, you'll need to run this command
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
733 for the cgi to work (it turns on the PATH_INFO cgi variable)::
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
734
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
735 adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
736
3799
ac4da2670516 trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3797
diff changeset
737 The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts``
1540
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
738 or ``c:\winnt\system32\inetsrv\adminsamples\`` or
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
739 ``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation.
3e65577ad6d7 minor changes
Richard Jones <richard@users.sourceforge.net>
parents: 1528
diff changeset
740
6370
45e8d10a9609 Update links in documentation
John Rouillard <rouilj@ieee.org>
parents: 6297
diff changeset
741 See:
45e8d10a9609 Update links in documentation
John Rouillard <rouilj@ieee.org>
parents: 6297
diff changeset
742
7136
a67f55c42476 fix links.
John Rouillard <rouilj@ieee.org>
parents: 7124
diff changeset
743 https://learn.microsoft.com/en-us/iis/web-dev-reference/server-variables
6370
45e8d10a9609 Update links in documentation
John Rouillard <rouilj@ieee.org>
parents: 6297
diff changeset
744
2988
f4023f1cc1d6 apply IE caching "fix" to automatically serve up all pages expired
Richard Jones <richard@users.sourceforge.net>
parents: 2979
diff changeset
745 More information about ISS setup may be found at:
f4023f1cc1d6 apply IE caching "fix" to automatically serve up all pages expired
Richard Jones <richard@users.sourceforge.net>
parents: 2979
diff changeset
746
7712
a03f8f681992 doc: fix links: 302/302, images from lfw.org, wayback for sc
John Rouillard <rouilj@ieee.org>
parents: 7707
diff changeset
747 https://learn.microsoft.com/en-us/iis/
2988
f4023f1cc1d6 apply IE caching "fix" to automatically serve up all pages expired
Richard Jones <richard@users.sourceforge.net>
parents: 2979
diff changeset
748
7311
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
749 Copy the ``share/roundup/cgi-bin/roundup-cgi``
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
750 (``frontends/roundup.cgi`` in source tree) file to your web
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
751 server's ``cgi-bin`` directory. You will need to configure it to
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
752 tell it where your tracker home is. You can do this either:
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
753
3303
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
754 Through an environment variable
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
755 Set the variable TRACKER_HOMES to be a colon (":") separated list of
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
756 name=home pairs (if you're using apache, the SetEnv directive can do this)
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
757
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
758 Directly in the ``roundup.cgi`` file itself
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
759 Add your instance to the TRACKER_HOMES variable as ``'name': 'home'``
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
760
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
761 The "name" part of the configuration will appear in the URL and identifies the
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
762 tracker (so you may have more than one tracker per cgi-bin script). Make sure
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
763 there are no spaces or other illegal characters in it (to be safe, stick to
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
764 letters and numbers). The "name" forms part of the URL that appears in the
3303
520eef0e0e91 fix installation docs referring to old-style configuration variables
Richard Jones <richard@users.sourceforge.net>
parents: 3297
diff changeset
765 tracker config "tracker :: web" variable, so make sure they match. The "home"
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
766 part of the configuration is the tracker home directory.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
767
2665
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
768 If you're using Apache, you can use an additional trick to hide the
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
769 ``.cgi`` extension of the cgi script. Place the ``roundup.cgi`` script
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
770 wherever you want it to be, rename it to just ``roundup``, and add a
2665
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
771 couple lines to your Apache configuration::
3799
ac4da2670516 trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3797
diff changeset
772
2665
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
773 <Location /path/to/roundup>
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
774 SetHandler cgi-script
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
775 </Location>
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
776
7d6dda802ca0 cgi install tip
Richard Jones <richard@users.sourceforge.net>
parents: 2594
diff changeset
777
4324
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
778 CGI-bin for Limited-Access Hosting
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
779 ----------------------------------
4324
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
780
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
781 If you are running in a shared-hosting environment or otherwise don't have
4656
bce631d8f24d issue2550738: Fixes for various documentation typos, thanks Nathan Russell
John Kristensen <john@jerrykan.com>
parents: 4510
diff changeset
782 permission to edit the system web server's configuration, but can create a
4324
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
783 ``.htaccess`` file then you may be able to use this approach.
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
784
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
785 1. Install flup_
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
786 2. Create a script ``roundup_stub`` in your server's ``cgi-bin`` directory
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
787 containing::
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
788
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
789 #!/usr/bin/env python
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
790
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
791 # if necessary modify the Python path to include the place you
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
792 # installed Roundup
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
793 #import sys
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
794 #sys.path.append('...')
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
795
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
796 # cgitb is needed for debugging in browser only
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
797 #import cgitb
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
798 #cgitb.enable()
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
799
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
800 # obtain the WSGI request dispatcher
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
801 from roundup.cgi.wsgi_handler import RequestDispatcher
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
802 tracker_home = '/path/to/tracker/home'
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
803 app = RequestDispatcher(tracker_home)
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
804
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
805 from flup.server.cgi import WSGIServer
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
806 WSGIServer(app).run()
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
807
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
808 3. Modify or created the ``.htaccess`` file in the desired (sub-)domain
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
809 directory to contain::
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
810
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
811 RewriteEngine On
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
812 RewriteBase /
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
813 RewriteRule ^(.*)$ /cgi-bin/roundup_stub/$1 [L]
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
814
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
815 Now loading the (sub-)domain in a browser should load the tracker web
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
816 interface. If you get a "500" error then enable the "cgitb" lines in the
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
817 stub to get some debugging information.
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
818
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
819 .. index:: pair: web interface; stand alone server
4324
c70762f2be4e flup setup docs from Christian Glass
Richard Jones <richard@users.sourceforge.net>
parents: 4317
diff changeset
820
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
821 Stand-alone Web Server
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
822 ----------------------
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
823
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
824 This approach will give you faster response than cgi-bin. You may
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
825 investigate using ProxyPass or similar configuration in apache to have your
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
826 tracker accessed through the same URL as other systems.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
827
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
828 The stand alone serveris used by the Docker image.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
829
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
830 The stand-alone web server is started with the command ``roundup-server``. It
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
831 has several options - display them with ``roundup-server -h``.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
832
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
833 The tracker home configuration is similar to the cgi-bin - you may either edit
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
834 the script to change the TRACKER_HOMES variable or you may supply the
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
835 name=home values on the command-line after all the other options.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
836
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
837 To make the server run in the background, use the "-d" option, specifying the
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
838 name of a file to write the server process id (pid) to.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
839
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
840
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
841 .. index:: pair: web interface; Zope
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
842
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
843 Zope Product - ZRoundup
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
844 -----------------------
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
845
7311
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
846 ZRoundup installs as a regular Zope product. Copy the
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
847 ``share/roundup/frontends/ZRoundup`` (frontends/ZRoundup in the
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
848 source tree) directory to your Products directory either in
4bbd1316db00 document location of frontends when installed and in source
John Rouillard <rouilj@ieee.org>
parents: 7310
diff changeset
849 INSTANCE_HOME/Products or the Zope code tree lib/python/Products.
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
850
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
851 When you next (re)start up Zope, you will be able to add a ZRoundup object
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
852 that interfaces to your new tracker.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
853
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
854 .. index:: ! triple: web interface; apache; mod_wsgi
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
855 ! single: wsgi; apache
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
856
5891
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
857 Apache HTTP Server with mod_wsgi
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
858 --------------------------------
5891
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
859
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
860 This is a work in progress thanks to Garth Jensen.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
861
5909
d57347ae6f25 Typo fixes in installation.txt doc.
John Rouillard <rouilj@ieee.org>
parents: 5908
diff changeset
862 See the main web site for `mod_wsgi`_ which include directions for
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
863 using mod_wsgi-express which is easier if you are not used to apache
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
864 configuration. Also there is the
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
865 `main mod_wsgi <https://modwsgi.readthedocs.io/en/develop/>`_ for more
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
866 detailed directions.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
867
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
868 Background
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
869 ~~~~~~~~~~
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
870
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
871 These notes were developed on a Microsoft Azure VM running Ubuntu
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
872 18.04 LTS. The instructions below assume:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
873
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
874 - python and roundup are already installed
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
875 - roundup is running in the system python instance (e.g. no virtual
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
876 environment)
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
877 - the tracker ``mytracker`` is installed in the ``trackers`` folder of
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
878 home directory of a user called ``admin``. Thus, the absolute path to
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
879 the tracker home directory is ``/home/admin/trackers/mytracker``.
7700
939e2edeab40 doc: use 'TEST-NET' IPv4 or IPv6 IP address ranges from RFC 6890
John Rouillard <rouilj@ieee.org>
parents: 7698
diff changeset
880 - the server has a static public IP address of 198.51.100.25
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
881
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
882 Install mod-wsgi
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
883 ~~~~~~~~~~~~~~~~
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
884
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
885 You can install/build it using the python package manager pip, or
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
886 install using the OS package manager (apt).
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
887
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
888 Pip install of mod_wsgi
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
889 '''''''''''''''''''''''
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
890
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
891 This is the tested method, and offers an easier path to get started,
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
892 but it does mean that you will need to keep up to date with any
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
893 security or other issues. If you use the packages supplied by your OS
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
894 vendor, you may get more timely updates and notifications.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
895
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
896 The mod_wsgi docs talk about two installation methods: (1) the
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
897 so-called CMMI method or (2) with pip. The pip method also provides an
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
898 admin script called ``mod_wsgi-express`` that can start up a
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
899 standalone instance of Apache directly from the command line with an
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
900 auto generated configuration. These instructions follow the pip
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
901 method.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
902
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
903
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
904 1. The `mod_wsgi`_ PyPi page lists prerequisites for various types of
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
905 systems. For Ubuntu, they are apache2 and apache2-dev. To see
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
906 installed apache packages, you can use ``dpkg -l | grep apache``.
5909
d57347ae6f25 Typo fixes in installation.txt doc.
John Rouillard <rouilj@ieee.org>
parents: 5908
diff changeset
907 If apache2 or apache2-dev are not installed, they install them
d57347ae6f25 Typo fixes in installation.txt doc.
John Rouillard <rouilj@ieee.org>
parents: 5908
diff changeset
908 with:
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
909
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
910 - ``sudo apt update``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
911 - ``sudo apt install apache2 apache2-dev``
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
912
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
913 2. If ``pip`` is not already installed, install it with
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
914 ``sudo apt install python-pip``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
915
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
916 If you are using python 3, use ``sudo apt-install python3-pip`` and
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
917 change references to pip in the directions to pip3.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
918 3. ``sudo pip install mod_wsgi``. In my case, I got warnings about
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
919 the user not owning directories, but it said it completed
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
920 "successfully."
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
921 4. For testing, open port 8000 for TCP on the server. For an Azure VM,
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
922 this is done with Azure Portal under ``Networking`` > ``Add inbound port``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
923 rule.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
924 5. Test with ``mod_wsgi-express start-server``. This should serve
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
925 up content on localhost port 8000. You can then direct a browser on
7347
73ef1f84c933 Prevent sample URL's from becoming links.
John Rouillard <rouilj@ieee.org>
parents: 7340
diff changeset
926 the server itself to ``http://localhost:8000/`` or on another machine at
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
927 the server's domain name or ip address followed by colon then 8000
7700
939e2edeab40 doc: use 'TEST-NET' IPv4 or IPv6 IP address ranges from RFC 6890
John Rouillard <rouilj@ieee.org>
parents: 7698
diff changeset
928 (e.g. ``http://198.51.100.25:8000/``). If successful, you should see a
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
929 Malt Whiskey image.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
930
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
931 Package manager install of mod_wsgi
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
932 '''''''''''''''''''''''''''''''''''
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
933
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
934 On debian (which should work for Ubuntu), install apache2 with
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
935 libapache2-mod-wsgi:
5891
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
936
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
937 - ``sudo apt update``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
938 - ``sudo apt install apache2 libapache2-mod-wsgi``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
939
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
940 this is the less tested method for installing mod_wsgi and may not
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
941 install mod_wsgi-express, which is used below. However there is an
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
942 example apache config included as part of `WSGI Variations`_ that can
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
943 be used to hand craft an apache config.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
944
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
945 You should make sure that the version you install is 3.5 or newer due
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
946 to security issues in older releases.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
947
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
948 Configure web interface via wsgi_handler
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
949 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
950
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
951 1. In the tracker's home directory create a ``wsgi.py`` file with the
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
952 following content (substituting ``/home/admin/trackers/mytracker``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
953 with the absolute path for your tracker's home directory):
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
954
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
955 .. code:: python
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
956
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
957 from roundup.cgi.wsgi_handler import RequestDispatcher
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
958 tracker_home = '/home/admin/trackers/mytracker'
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
959 application = RequestDispatcher(tracker_home)
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
960
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
961 To run the tracker on Port 8000 as a foreground process
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
962 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
963
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
964 1. Change the ``tracker.web`` url in ``config.ini`` to port 8000 at the
7700
939e2edeab40 doc: use 'TEST-NET' IPv4 or IPv6 IP address ranges from RFC 6890
John Rouillard <rouilj@ieee.org>
parents: 7698
diff changeset
965 server domain name or ip address (e.g. ``http://198.51.100.25:8000/``).
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
966 2. Open port 8000 for TCP on the server if you didn't already do so.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
967 3. ``cd`` to your tracker home directory, then run
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
968 ``mod_wsgi-express start-server wsgi.py``.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
969 4. Test by directing a browser on another machine to the url you set
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
970 ``tracker.web`` to in ``config.ini``.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
971
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
972 Run tracker as background daemon
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
973 ''''''''''''''''''''''''''''''''
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
974
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
975 To run the tracker on Port 80 or as a background process, you'll need
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
976 to configure a UNIX group with appropriate privileges as described in
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
977 `UNIX environment steps`_. These steps are summarized here:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
978
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
979 1. To add a group named "mytrackergrp" run: ``sudo groupadd mytrackergrp``.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
980 2. Add the owner of the tracker home (admin in this example) run:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
981 ``sudo usermod -a -G mytrackergrp admin``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
982 3. Add user that runs Apache (the default on Ubuntu is www-data) run:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
983 ``sudo usermod -a -G mytrackergrp www-data``
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
984 4. Add user mail service runs as (e.g. daemon) run:
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
985 ``sudo usermod -a -G mytrackergrp daemon``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
986 5. Change group of the database in the tracker folder run:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
987 ``sudo chgrp -R mytrackergrp ~/trackers/mytracker``.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
988 6. Make sure group can write to the database, and any new files created
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
989 in the database will be owned by the group run:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
990 ``sudo chmod -R g+sw ~/trackers/mytracker/db``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
991
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
992 To run mod_wsgi on PORT 80
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
993 ''''''''''''''''''''''''''
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
994
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
995 1. Change the ``tracker.web`` url in ``config.ini`` to the server url
7700
939e2edeab40 doc: use 'TEST-NET' IPv4 or IPv6 IP address ranges from RFC 6890
John Rouillard <rouilj@ieee.org>
parents: 7698
diff changeset
996 with no port designator. E.g. ``http://198.51.100.25``.
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
997 2. Open port 80 on the server for TCP traffic if it isn't open already.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
998 3. Stop the system instance of Apache to make sure it isn't holding on
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
999 to port 80 run: ``sudo service apache2 stop``.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1000
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1001 To run as a foreground process
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1002 ++++++++++++++++++++++++++++++
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1003
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1004 1. From the tracker home directory, run
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1005 ``sudo mod_wsgi-express start-server wsgi.py --port 80 --user admin --group mytrackergrp``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1006
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1007 To run as a background process
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1008 ++++++++++++++++++++++++++++++
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1009
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1010 1. From the tracker home directory, bash
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1011 ``sudo mod_wsgi-express setup-server wsgi.py --port=80 --user admin --group mytrackergrp --server-root=/etc/mod_wsgi-express-80``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1012 2. Then, run ``sudo /etc/mod_wsgi-express-80/apachectl start``
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1013 3. To stop, run ``sudo /etc/mod_wsgi-express-80/apachectl stop``
5891
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
1014
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1015 .. index:: triple: web interface; apache; mod_python (depricated)
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1016
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1017 Apache HTTP Server with mod_python
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1018 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1019
5891
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
1020 As of roundup 2.0, mod_python support is deprecated. The apache.py
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
1021 file is still available, but may be limited to working for Python 2
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
1022 only. Using mod_wsgi with Apache is the recommended way to deploy
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
1023 roundup under apache.
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
1024
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1025 `Mod_python`_ is an `Apache`_ module that embeds the Python interpreter
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1026 within the server. Running Roundup this way is much faster than all
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1027 above options and, like `web server cgi-bin`_, allows you to use HTTPS
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1028 protocol. The drawback is that this setup is more complicated.
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1029
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1030 The following instructions were tested on apache 2.0 with mod_python 3.1.
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1031 If you are using older versions, your mileage may vary.
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1032
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1033 Mod_python uses OS threads. If your apache was built without threads
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1034 (quite commonly), you must load the threading library to run mod_python.
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1035 This is done by setting ``LD_PRELOAD`` to your threading library path
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1036 in apache ``envvars`` file. Example for gentoo linux (``envvars`` file
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1037 is located in ``/usr/lib/apache2/build/``)::
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1038
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1039 LD_PRELOAD=/lib/libpthread.so.0
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1040 export LD_PRELOAD
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1041
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1042 Example for FreeBSD (``envvars`` is in ``/usr/local/sbin/``)::
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1043
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1044 LD_PRELOAD=/usr/lib/libc_r.so
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1045 export LD_PRELOAD
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1046
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1047 Next, you have to add Roundup trackers configuration to apache config.
4249
87b3e905ae2e fixed typos in the installation instructions
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4226
diff changeset
1048 Roundup apache interface uses the following options specified with
87b3e905ae2e fixed typos in the installation instructions
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4226
diff changeset
1049 ``PythonOption`` directives:
2559
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1050
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1051 TrackerHome:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1052 defines the tracker home directory - the directory that was specified
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1053 when you did ``roundup-admin init``. This option is required.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1054
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1055 TrackerLanguage:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1056 defines web user interface language. mod_python applications do not
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1057 receive OS environment variables in the same way as command-line
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1058 programs, so the language cannot be selected by setting commonly
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1059 used variables like ``LANG`` or ``LC_ALL``. ``TrackerLanguage``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1060 value has the same syntax as values of these environment variables.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1061 This option may be omitted.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1062
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1063 TrackerDebug:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1064 run the tracker in debug mode. Setting this option to ``yes`` or
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1065 ``true`` has the same effect as running ``roundup-server -t debug``:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1066 the database schema and used html templates are rebuilt for each
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1067 HTTP request. Values ``no`` or ``false`` mean that all html
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1068 templates for the tracker are compiled and the database schema is
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1069 checked once at startup. This is the default behaviour.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1070
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1071 TrackerTiming:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1072 has nearly the same effect as environment variable ``CGI_SHOW_TIMING``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1073 for standalone roundup server. The difference is that setting this
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1074 option to ``no`` or ``false`` disables timings display. Value
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1075 ``comment`` writes request handling times in html comment, and
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1076 any other non-empty value makes timing report visible. By default,
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1077 timing display is disabled.
2945
98efa80f0f90 added mod_python options TrackerDebug and TrackerTiming
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2921
diff changeset
1078
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1079 In the following example we have two trackers set up in
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1080 ``/var/db/roundup/support`` and ``/var/db/roundup/devel`` and accessed
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1081 as ``https://my.host/roundup/support/`` and ``https://my.host/roundup/devel/``
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1082 respectively (provided Apache has been set up for SSL of course).
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1083 Having them share same parent directory allows us to
2559
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1084 reduce the number of configuration directives. Support tracker has
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1085 russian user interface. The other tracker (devel) has english user
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1086 interface (default).
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1087
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1088 Static files from ``html`` directory are served by apache itself - this
4249
87b3e905ae2e fixed typos in the installation instructions
Bernhard Reiter <Bernhard.Reiter@intevation.de>
parents: 4226
diff changeset
1089 is quicker and generally more robust than doing that from python.
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1090 Everything else is aliased to dummy (non-existing) ``py`` file,
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1091 which is handled by mod_python and our roundup module.
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1092
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1093 Example mod_python configuration::
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1094
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1095 #################################################
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1096 # Roundup Issue tracker
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1097 #################################################
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1098 # enable Python optimizations (like 'python -O')
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1099 PythonOptimize On
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1100 # let apache handle static files from 'html' directories
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1101 AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1102 # everything else is handled by roundup web UI
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1103 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1104 # roundup requires a slash after tracker name - add it if missing
3965
248c3a7bc94d seems like a reasonable patch
Richard Jones <richard@users.sourceforge.net>
parents: 3949
diff changeset
1105 RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1106 # common settings for all roundup trackers
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1107 <Directory /var/db/roundup/*>
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1108 Order allow,deny
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1109 Allow from all
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1110 AllowOverride None
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1111 Options None
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1112 AddHandler python-program .py
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1113 PythonHandler roundup.cgi.apache
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1114 # uncomment the following line to see tracebacks in the browser
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1115 # (note that *some* tracebacks will be displayed anyway)
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1116 #PythonDebug On
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1117 </Directory>
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1118 # roundup tracker homes
2559
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1119 <Directory /var/db/roundup/support>
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1120 PythonOption TrackerHome /var/db/roundup/support
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1121 PythonOption TrackerLanguage ru
6c096b4aea67 added description and example of mod_python interface option TrackerLanguage
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2554
diff changeset
1122 </Directory>
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1123 <Directory /var/db/roundup/devel>
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1124 PythonOption TrackerHome /var/db/roundup/devel
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1125 </Directory>
3965
248c3a7bc94d seems like a reasonable patch
Richard Jones <richard@users.sourceforge.net>
parents: 3949
diff changeset
1126
3814
a612bdc6b1d3 thanks alex
Richard Jones <richard@users.sourceforge.net>
parents: 3799
diff changeset
1127 Notice that the ``/var/db/roundup`` path shown above refers to the directory
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1128 in which the tracker homes are stored. The actual value will thus depend on
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1129 your system.
3799
ac4da2670516 trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3797
diff changeset
1130
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1131 .. index:: windows; apache config
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1132
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1133 On Windows the corresponding lines will look similar to these::
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1134
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1135 AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1136 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1137 <Directory C:/DATA/roundup/*>
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1138 <Directory C:/DATA/roundup/support>
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1139 <Directory C:/DATA/roundup/devel>
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1140
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1141 In this example the directory hosting all of the tracker homes is
3799
ac4da2670516 trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3797
diff changeset
1142 ``C:\DATA\roundup``. (Notice that you must use forward slashes in paths
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1143 inside the httpd.conf file!)
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1144
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1145 The URL for accessing these trackers then become:
7347
73ef1f84c933 Prevent sample URL's from becoming links.
John Rouillard <rouilj@ieee.org>
parents: 7340
diff changeset
1146 ``http://<roundupserver>/roundup/support/`` and
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1147 ``http://<roundupserver>/roundup/devel/``
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1148
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1149 Note that in order to use https connections you must set up Apache for secure
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
1150 serving with SSL.
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
1151
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1152 Nginx HTTP Server
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1153 -----------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1154
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1155 This configuration uses Gunicorn to run Roundup behind an Nginx proxy.
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1156 The proxy also compresses the data using gzip. The url for the tracker
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1157 in config.ini should be ``https://tracker.example.org``.
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1158
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1159 .. code::
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1160
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1161 user nginx;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1162 worker_processes auto;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1163 worker_rlimit_nofile 10000;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1164
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1165 error_log /var/log/nginx/global-error.log;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1166 pid /var/run/nginx.pid;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1167
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1168 events {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1169 worker_connections 1024;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1170 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1171
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1172 upstream tracker-tracker {
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1173 # Gunicorn uses this socket for communication
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1174 server unix:/var/run/roundup/tracker.sock fail_timeout=0;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1175 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1176
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1177 http {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1178 include /etc/nginx/mime.types;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1179 default_type application/octet-stream;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1180
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1181 log_format main '$remote_addr - $remote_user [$time_local] "$request" '
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1182 '$status $body_bytes_sent "$http_referer" '
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1183 '"$http_user_agent" "$http_x_forwarded_for"';
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1184
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1185 access_log /var/log/nginx/global-access.log main;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1186 sendfile on;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1187 tcp_nopush on;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1188 tcp_nodelay on;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1189 server_tokens off;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1190
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1191 gzip_http_version 1.1;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1192 gzip_proxied any;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1193 gzip_min_length 500;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1194 # default comp_level is 1
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1195 gzip_comp_level 6;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1196 gzip_disable msie6
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1197 gzip_types text/plain text/css
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1198 text/xml application/xml
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1199 text/javascript application/javascript
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1200 text/json application/json;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1201 # upstream proxies need to match Accept-Encoding as
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1202 # part of their cache check
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1203 gzip_vary on
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1204
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1205 server {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1206 listen 80;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1207 server_name tracker.example.org;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1208
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1209 location /.well-known/acme-challenge/ {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1210 alias /etc/lego/.well-known/acme-challenge/;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1211 try_files $uri =404;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1212 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1213
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1214 location / {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1215 return 301 https://$http_host$request_uri;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1216 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1217 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1218
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1219 server {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1220 listen 443 ssl;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1221 server_name tracker.example.org;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1222 include mime.types;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1223
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1224 # By default use the snakeoil certificate...
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1225 # change this if you are using a real SSL cert
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1226 ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1227 ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1228
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1229 # These are useful for @@files where roundup is bypassed.
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1230 # but can be set by roundup as well. See:
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1231 # https://wiki.roundup-tracker.org/AddingContentSecurityPolicy
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1232 # which also sets other security headers.
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1233 add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload";
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1234 add_header X-Frame-Options "sameorigin";
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1235 add_header X-Xss-Protection "1; mode=block";
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1236 add_header X-Content-Type-Options "nosniff";
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1237 add_header X-Permitted-Cross-Domain-Policies "none";
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1238
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1239 error_log /var/log/nginx/roundup-tracker.error.log;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1240 access_log /var/log/nginx/roundup-tracker.access.log
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1241
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1242 root /home/roundup/trackers/tracker/;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1243
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1244 # have nginx return files from @@file directly rather than
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1245 # going though roundup
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1246 location /@@file/ {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1247 rewrite ^/@@file/(.*) /html/$1 break;
7499
a072331c843b Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents: 7453
diff changeset
1248 # note that you can not use cache control (see customising doc)
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1249 # in roundup to set the expires headers since we are
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1250 # bypassing roundup. Consider using a map or different
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1251 # location stanzas to vary the expiration times.
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1252 expires 1h;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1253 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1254
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1255 location / {
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1256 # must define tracker-tracker in upstream stanza
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1257 proxy_pass http://tracker-tracker/;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1258 proxy_set_header Host $host;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1259 proxy_set_header X-Real-IP $remote_addr;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1260 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1261 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1262 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1263 }
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1264
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1265
6555
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1266 FastCGI (Cherokee, Hiawatha, lighttpd)
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1267 --------------------------------------
6555
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1268
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1269 The Hiawatha and lighttpd web servers can run Roundup using FastCGI.
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1270 Cherokee can run FastCGI but it also supports wsgi directly using a
7524
6dc0f7afde80 Fix grammar.
John Rouillard <rouilj@ieee.org>
parents: 7523
diff changeset
1271 wsgi server like uWSGI, Gnuicorn etc.
6555
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1272
7124
e65f808d55eb fix typo
John Rouillard <rouilj@ieee.org>
parents: 7065
diff changeset
1273 To run Roundup using FastCGI, the flup_ package can be used under
6555
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1274 Python 2 and Python 3. We don't have a detailed config for this, but
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1275 the basic idea can be found at:
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1276 https://flask.palletsprojects.com/en/2.0.x/deploying/fastcgi/
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1277
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1278 If you have deployed Roundup using FastCGI and flup we welcome example
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1279 configuration files and instructions.
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1280
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1281 .. _flup: https://pypi.org/project/flup/
34cbd0e633d2 Added FastCGI deployment info, updated Docker docs; docker-compose added
John Rouillard <rouilj@ieee.org>
parents: 6522
diff changeset
1282
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1283 WSGI Variations
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1284 ---------------
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1285
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1286 .. index:: triple: web interface; apache; mod_wsgi
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1287 single: wsgi; apache
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1288
5938
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1289 Apache Alternate
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1290 ~~~~~~~~~~~~~~~~
5938
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1291
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1292 This method from Thomas Arendsen Hein goes into a bit more detail and
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1293 is designed to allow you to run multiple roundup trackers each under
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1294 their own user.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1295
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1296 The tracker instances are read-only to the tracker user and located
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1297 under /srv/roundup/. The (writable) data files are stored in the home
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1298 directory of the user running the tracker.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1299
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1300 To install roundup, download and unpack a distribution tarball and run
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1301 the following as user "roundup"::
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1302
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1303 python setup.py build_doc
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1304 python setup.py sdist --manifest-only
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1305 python setup.py install --home="/home/roundup/install" --force
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1306
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1307 Create a user roundup-foo, group roundup-foo to run the tracker. Add
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1308 the following apache config to
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1309 /etc/apache2/sites-available/roundup-foo (under debian/Ubunutu, modify
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1310 as needed):
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1311
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1312 .. code:: ApacheConf
3736
a2d22d0de0bc WSGI support via roundup.cgi.wsgi_handler
Richard Jones <richard@users.sourceforge.net>
parents: 3731
diff changeset
1313
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1314 ServerAdmin webmaster@example.com
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1315 ErrorLog /var/log/apache2/error.log
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1316
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1317 LogLevel notice
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1318
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1319 DocumentRoot /var/www/
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1320
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1321 <VirtualHost *:80>
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1322 CustomLog /var/log/apache2/access.log vhost_combined
3736
a2d22d0de0bc WSGI support via roundup.cgi.wsgi_handler
Richard Jones <richard@users.sourceforge.net>
parents: 3731
diff changeset
1323
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1324 # allow access to roundup docs
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1325 Alias /doc/ /home/roundup/install/share/doc/roundup/html/
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1326
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1327 # make apache serve static assets like css rather than
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1328 # having roundup serve the files
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1329 Alias /foo/@@file/ /srv/roundup/foo/html/
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1330
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1331 # make /foo into /foo/
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1332 RedirectMatch permanent ^/(foo)$ /$1/
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1333
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1334 # start a wsgi daemon process running as user roundup-foo
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1335 # in group roundup-foo. This also changes directory to
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1336 # ~roundup-foo before it starts roundup.wsgi.
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1337 WSGIDaemonProcess roundup-foo display-name=roundup-foo user=roundup-foo group=roundup-foo threads=25
3736
a2d22d0de0bc WSGI support via roundup.cgi.wsgi_handler
Richard Jones <richard@users.sourceforge.net>
parents: 3731
diff changeset
1338
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1339 # make tracker available at /foo and tie it into the
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1340 # wsgi script below.
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1341 WSGIScriptAlias /foo /srv/roundup/foo/roundup.wsgi
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1342 <Location /foo>
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1343 WSGIProcessGroup roundup-foo
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1344 </Location>
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1345 </VirtualHost>
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1346
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1347 The directory ~roundup-foo should have:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1348
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1349 * a ``db`` subdirectory where messages and files will be stored
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1350 * a symbolic link called ``instance`` to /srv/roundup/foo which has
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1351 been initialised using ``roundup-admin``.
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1352
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1353 The `Apache HTTP Server with mod_wsgi`_ section above has a simple
5910
aec362e31fcd doc/installation.txt: fix typo
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5909
diff changeset
1354 WSGI handler. This is an enhanced version to be put into
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1355 ``/srv/roundup/foo/roundup.wsgi``.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1356
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1357 .. code:: python
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1358
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1359 import sys, os
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1360 sys.stdout = sys.stderr
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1361
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1362 enabled = True
3736
a2d22d0de0bc WSGI support via roundup.cgi.wsgi_handler
Richard Jones <richard@users.sourceforge.net>
parents: 3731
diff changeset
1363
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1364 if enabled:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1365 # Add the directory with the roundup installation
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1366 # subdirectory to the python path.
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1367 sys.path.insert(0, '/home/roundup/install/lib/python')
3736
a2d22d0de0bc WSGI support via roundup.cgi.wsgi_handler
Richard Jones <richard@users.sourceforge.net>
parents: 3731
diff changeset
1368
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1369 # obtain the WSGI request dispatcher
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1370 from roundup.cgi.wsgi_handler import RequestDispatcher
5911
133efe1fbff7 doc/installation.txt: replace tabs, remove trailing spaces
Thomas Arendsen Hein <thomas@intevation.de>
parents: 5910
diff changeset
1371
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1372 tracker_home = os.path.join(os.getcwd(), 'instance')
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1373 application = RequestDispatcher(tracker_home)
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1374 else:
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1375 def application(environ, start_response):
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1376 status = '503 Service Unavailable'
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1377 output = 'service is down for maintenance'
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1378 response_headers = [('Content-type', 'text/plain'),
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1379 ('Content-Length', str(len(output)))]
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1380 start_response(status, response_headers)
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1381 return [output]
3736
a2d22d0de0bc WSGI support via roundup.cgi.wsgi_handler
Richard Jones <richard@users.sourceforge.net>
parents: 3731
diff changeset
1382
5908
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1383 This handler allows you to temporarily disable the tracker by setting
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1384 "enabled = False", apache will automatically detect the changed
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1385 roundup.wsgi file and reload it.
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1386
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1387 One last change is needed. In the tracker's config.ini change the db
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1388 parameter in the [main] section to be /home/roundup-foo/db. This will
c7ab00dd6502 First pass at updated wsgi documentation
John Rouillard <rouilj@ieee.org>
parents: 5891
diff changeset
1389 put the files and messages in the db directory for the user.
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1390
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1391 .. index:: pair: web interface; Gunicorn
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1392 single: wsgi; Gunicorn
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1393
5938
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1394 Gunicorn Installation
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1395 ~~~~~~~~~~~~~~~~~~~~~
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1396
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1397 To run with Gunicorn use ``pip install gunicorn``. This configuration
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1398 uses a front end web server like nginx, hiawatha, or apache configured as
5938
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1399 a reverse proxy. See your web server's documentation on how to set it
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1400 up as a reverse proxy.
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1401
6390
7c852cad2ca8 Add wsgi.py to frontends. Update docs.
John Rouillard <rouilj@ieee.org>
parents: 6372
diff changeset
1402 The file wsgi.py (obtained from ``frontends/wsgi.py``) should be in
7c852cad2ca8 Add wsgi.py to frontends. Update docs.
John Rouillard <rouilj@ieee.org>
parents: 6372
diff changeset
1403 the current directory with the contents::
5938
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1404
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1405 # if roundup is not installed on the default PYTHONPATH
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1406 # set it here with:
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1407 import sys
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1408 sys.path.append('/path/to/roundup/install/directory')
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1409
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1410 # obtain the WSGI request dispatcher
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1411 from roundup.cgi.wsgi_handler import RequestDispatcher
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1412 tracker_home = '/path/to/tracker/install/directory'
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1413
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1414 app = RequestDispatcher(tracker_home)
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1415
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1416 Assuming the proxy forwards /tracker, run Gunicorn as::
5938
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1417
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1418 SCRIPT_NAME=/tracker gunicorn --bind 127.0.0.1:8917 --timeout=10 wsgi:app
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1419
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1420 this runs roundup at port 8917 on the loopback interface. You should
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1421 configure the reverse proxy to talk to 127.0.0.1 at port 8917.
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1422 If you want you can use a unix domain socket instead. Example:
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1423 ``--bind unix:///var/run/roundup/tracker.sock`` would be used for the
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
1424 nginx configuration below.
5938
16eec1c41e0e Add basic gunicorn configuration mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5911
diff changeset
1425
7601
ac8dc6e7a8e3 docs: add link to article on using gunicorn with docker.
John Rouillard <rouilj@ieee.org>
parents: 7581
diff changeset
1426 If you are customizing a docker continer to use gunicorn, see
ac8dc6e7a8e3 docs: add link to article on using gunicorn with docker.
John Rouillard <rouilj@ieee.org>
parents: 7581
diff changeset
1427 https://pythonspeed.com/articles/gunicorn-in-docker/.
ac8dc6e7a8e3 docs: add link to article on using gunicorn with docker.
John Rouillard <rouilj@ieee.org>
parents: 7581
diff changeset
1428
6163
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1429 .. index:: pair: web interface; uWSGI
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1430 single: wsgi; uWSGI
c2fd254c9257 Doc updates/indexing.
John Rouillard <rouilj@ieee.org>
parents: 6099
diff changeset
1431
5940
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1432 uWSGI Installation
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1433 ~~~~~~~~~~~~~~~~~~
5940
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1434
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1435 For a basic roundup install using uWSGI behind a front end server,
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1436 install uwsgi and the python3 (or python) plugin. Then run::
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1437
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1438 uwsgi --http-socket 127.0.0.1:8917 \
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1439 --plugin python3 --mount=/tracker=wsgi.py \
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1440 --manage-script-name --callable app
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1441
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1442 using the same wsgi.py as was used for Gunicorn. If you get path not
5940
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1443 found errors, check the mount option. The /tracker entry must match
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1444 the path used for the [tracker] web value in the tracker's config.ini.
459426a8c61e Add basic uwsgi setup.
John Rouillard <rouilj@ieee.org>
parents: 5938
diff changeset
1445
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1446 Configure an Email Interface
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1447 ============================
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1448
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1449 If you don't want to use the email component of Roundup, then remove the
1514
c706e55896d8 minor doc bug
Richard Jones <richard@users.sourceforge.net>
parents: 1507
diff changeset
1450 "``nosyreaction.py``" module from your tracker "``detectors``" directory.
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1451
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
1452 See `platform-specific notes`_ for steps that may be needed on your system.
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
1453
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1454 There are five supported ways to get emailed issues into the
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1455 Roundup tracker. You should pick ONE of the following, all
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1456 of which will continue my example setup from above:
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1457
3799
ac4da2670516 trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3797
diff changeset
1458 As a mail alias pipe process
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1459 ----------------------------
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1460
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1461 Set up a mail alias called "issue_tracker" as (include the quote marks):
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1462 "``|/usr/bin/python /usr/bin/roundup-mailgw <tracker_home>``"
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1463 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed).
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1464
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1465 In some installations (e.g. RedHat Linux and Fedora Core) you'll need to
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1466 set up smrsh so sendmail will accept the pipe command. In that case,
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1467 symlink ``/etc/smrsh/roundup-mailgw`` to "``/usr/bin/roundup-mailgw``"
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1468 and change the command to::
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1469
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1470 |roundup-mailgw /opt/roundup/trackers/support
3799
ac4da2670516 trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3797
diff changeset
1471
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1472 To test the mail gateway on unix systems, try::
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1473
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1474 echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1475
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1476 Be careful that some mail systems (postfix for example) will impose
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1477 limits on processes they spawn. In particular postfix can set a file
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1478 size limit that is inherited by the mailgw. If the database files
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1479 (anydbm, sqlite) exceed this limit, *this can cause your Roundup
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1480 database to become corrupted.*
3722
41feeed84caa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3666
diff changeset
1481
41feeed84caa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3666
diff changeset
1482
3447
83e358352e6e minor correction to recent addition by Faheem Mitha
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3446
diff changeset
1483 As a custom router/transport using a pipe process (Exim4 specific)
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1484 ------------------------------------------------------------------
3444
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1485
3446
2325b221bf47 link to exim site
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3444
diff changeset
1486 The following configuration snippets for `Exim 4`_ configuration
3444
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1487 implement a custom router & transport to accomplish mail delivery to
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1488 roundup-mailgw. A configuration for Exim3 is similar but not
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1489 included, since Exim3 is considered obsolete.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1490
7136
a67f55c42476 fix links.
John Rouillard <rouilj@ieee.org>
parents: 7124
diff changeset
1491 .. _Exim 4: https://www.exim.org/
3446
2325b221bf47 link to exim site
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3444
diff changeset
1492
3444
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1493 This configuration is similar to the previous section, in that it uses
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1494 a pipe process. However, there are advantages to using a custom
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1495 router/transport process, if you are using Exim.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1496
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1497 * This avoids privilege escalation, since otherwise the pipe process
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1498 will run as the mail user, typically mail. The transport can be
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1499 configured to run as the user appropriate for the task at hand. In the
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1500 transport described in this section, Exim4 runs as the unprivileged
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1501 user ``roundup``.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1502
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1503 * Separate configuration is not required for each tracker
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1504 instance. When a email arrives at the server, Exim passes it through
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1505 the defined routers. The roundup_router looks for a match with one of
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1506 the roundup directories, and if there is one it is passed to the
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1507 roundup_transport, which uses the pipe process described in the
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1508 previous section (`As a mail alias pipe process`_).
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1509
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1510 The matching is done in the line::
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1511
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1512 require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1513
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1514 The following configuration has been tested on Debian Sarge with
3799
ac4da2670516 trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3797
diff changeset
1515 Exim4.
3444
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1516
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1517 .. note::
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1518 The Debian Exim4 packages don't allow pipes in alias files
3444
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1519 by default, so the method described in the section `As a mail alias
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1520 pipe process`_ will not work with the default configuration. However,
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1521 the method described in this section does. See the discussion in
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1522 ``/usr/share/doc/exim4-config/README.system_aliases`` on any Debian
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1523 system with Exim4 installed.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1524
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1525 For more Debian-specific information, see suggested addition to
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1526 README.Debian in
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
1527 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283, which will
3444
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1528 hopefully be merged into the Debian package eventually.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1529
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1530 This config makes a few assumptions:
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1531
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1532 * That the mail address corresponding to the tracker instance has the
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1533 same name as the directory of the tracker instance, i.e. the mail
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1534 interface address corresponding to a Roundup instance called
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1535 ``/var/lib/roundup/trackers/mytracker`` is ``mytracker@your.host``.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1536
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1537 * That (at least) all the db subdirectories of all the tracker
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1538 instances (ie. ``/var/lib/roundup/trackers/*/db``) are owned by the same
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1539 user, in this case, 'roundup'.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1540
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1541 * That if the ``schema.py`` file exists, then the tracker is ready for
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1542 use. Another option is to use the ``config.ini`` file (this changed
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1543 in 0.8 from ``config.py``).
3444
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1544
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1545 Macros for Roundup router/transport. Should be placed in the macros
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1546 section of the Exim4 config::
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1547
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1548 # Home dir for your Roundup installation
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1549 ROUNDUP_HOME=/var/lib/roundup/trackers
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1550
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1551 # User and group for Roundup.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1552 ROUNDUP_USER=roundup
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1553 ROUNDUP_GROUP=roundup
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1554
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1555 Custom router for Roundup. This will (probably) work if placed at the
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1556 beginning of the router section of the Exim4 config::
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1557
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1558 roundup_router:
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1559 driver = accept
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1560 # The config file config.ini seems like a more natural choice, but the
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1561 # file config.py was replaced by config.ini in 0.8, and schema.py needs
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1562 # to be present too.
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1563 require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1564 transport = roundup_transport
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1565
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1566 Custom transport for Roundup. This will (probably) work if placed at
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1567 the beginning of the router section of the Exim4 config::
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1568
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1569 roundup_transport:
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1570 driver = pipe
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1571 command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1572 current_directory = ROUNDUP_HOME
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1573 home_directory = ROUNDUP_HOME
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1574 user = ROUNDUP_USER
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1575 group = ROUNDUP_GROUP
0da93b338457 exim configuration instructions (from [SF#1393860])
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3421
diff changeset
1576
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1316
diff changeset
1577 As a regular job using a mailbox source
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1578 ---------------------------------------
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1579
3405
292fbed108ca *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3335
diff changeset
1580 Set ``roundup-mailgw`` up to run every 10 minutes or so. For example
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1581 (substitute ``/usr/bin`` for wherever roundup-mailgw is installed)::
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1582
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1583 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox <mail_spool_file>
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1584
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1585 Where the ``mail_spool_file`` argument is the location of the roundup submission
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1586 user's mail spool. On most systems, the spool for a user "issue_tracker"
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1587 will be "``/var/mail/issue_tracker``".
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1588
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1316
diff changeset
1589 As a regular job using a POP source
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1590 -----------------------------------
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1591
3405
292fbed108ca *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3335
diff changeset
1592 To retrieve from a POP mailbox, use a *cron* entry similar to the mailbox
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1593 one (substitute ``/usr/bin`` for wherever roundup-mailgw is
3405
292fbed108ca *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3335
diff changeset
1594 installed)::
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1595
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1596 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop <pop_spec>
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1316
diff changeset
1597
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1598 where pop_spec is "``username:password@server``" that specifies the roundup
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1599 submission user's POP account name, password and server.
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1600
7503
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1601 apop (authenticated) and pops (pop over ssl) methods are also
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1602 supported. See `the section on mailgw in the admin guide
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1603 <admin_guide.html#mail-gateway-script-command-line>`_.
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1604
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1605 On windows, you would set up the command `using the windows scheduler`_.
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1316
diff changeset
1606
2211
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1607 As a regular job using an IMAP source
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1608 -------------------------------------
2211
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1609
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1610 To retrieve from an IMAP mailbox, use a *cron* entry similar to the
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1611 POP one (substitute ``/usr/bin`` for wherever roundup-mailgw is
3405
292fbed108ca *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3335
diff changeset
1612 installed)::
2211
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1613
3524
ed82c2c6ee34 fix doc
Richard Jones <richard@users.sourceforge.net>
parents: 3523
diff changeset
1614 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support imap <imap_spec>
2211
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1615
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1616 where imap_spec is "``username:password@server``" that specifies the roundup
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1617 submission user's IMAP account name, password and server. You may
7503
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1618 optionally include a mailbox to use other than the default ``INBOX`` with::
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1619
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1620 imap username:password@server mailbox
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1621
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1622 If you have a secure (ie. HTTPS) IMAP server then you may use
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1623 ``imaps`` in place of ``imap`` in the command to use a securnae
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1624 connection. To use imap with CRAM or OAUTH, see `the section on
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1625 mailgw in the admin guide
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1626 <admin_guide.html#mail-gateway-script-command-line>`_ .
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1627
7b6278da3faa Update roundup-mailgw install with other methods; formatting
John Rouillard <rouilj@ieee.org>
parents: 7501
diff changeset
1628 As with the POP job, on windows, you would set up the command
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1629 `using the windows scheduler`_.
2211
272b654b1227 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2186
diff changeset
1630
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
1631
1939
1303c208419d some updates that were sitting on disk
Richard Jones <richard@users.sourceforge.net>
parents: 1913
diff changeset
1632 UNIX Environment Steps
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1633 ======================
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1634
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
1635 Each tracker ideally should have its own UNIX group, so create
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1636 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1637 you're using NIS). To continue with my examples so far, I would
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1638 create the UNIX group 'support', although the name of the UNIX
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
1639 group does not have to be the same as the tracker name. To this
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1640 'support' group I then add all of the UNIX usernames who will be
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
1641 working with this Roundup tracker. In addition to 'real' users,
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1642 the Roundup email gateway will need to have permissions to this
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1643 area as well, so add the user your mail service runs as to the
1574
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
1644 group (typically "mail" or "daemon"). The UNIX group might then
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
1645 look like::
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1646
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1647 support:*:1002:jblaine,samh,geezer,mail
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1648
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1649 If you intend to use the web interface (as most people do), you
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1650 should also add the username your web server runs as to the group.
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1651 My group now looks like this::
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1652
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1653 support:*:1002:jblaine,samh,geezer,mail,apache
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1654
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
1655 The tracker "db" directory should be chmod'ed g+sw so that the group can
1078
344bad728d10 more tweakage of help display and style issues
Richard Jones <richard@users.sourceforge.net>
parents: 1049
diff changeset
1656 write to the database, and any new files created in the database will be owned
344bad728d10 more tweakage of help display and style issues
Richard Jones <richard@users.sourceforge.net>
parents: 1049
diff changeset
1657 by the group.
344bad728d10 more tweakage of help display and style issues
Richard Jones <richard@users.sourceforge.net>
parents: 1049
diff changeset
1658
2594
c0d6d5004464 rdbms doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2559
diff changeset
1659 If you're using the mysql or postgresql backend then you'll need to ensure
c0d6d5004464 rdbms doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2559
diff changeset
1660 that the tracker user has appropriate permissions to create/modify the
c0d6d5004464 rdbms doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2559
diff changeset
1661 database. If you're using roundup.cgi, the apache user needs permissions
c0d6d5004464 rdbms doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2559
diff changeset
1662 to modify the database. Alternatively, explicitly specify a database login
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2818
diff changeset
1663 in ``rdbms`` -> ``user`` and ``password`` in ``config.ini``.
2594
c0d6d5004464 rdbms doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2559
diff changeset
1664
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1665 An alternative to the above is to create a new user who has the sole
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1666 responsibility of running roundup. This user:
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1667
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1668 1. runs the CGI interface daemon
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1669 2. runs regular polls for email
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1670 3. runs regular checks (using cron) to ensure the daemon is up
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1671 4. optionally has no login password so that nobody but the "root" user
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
1672 may actually login and play with the roundup setup.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1673
3754
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1674 If you're using a Linux system (e.g. Fedora Core) with SELinux enabled,
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1675 you will need to ensure that the db directory has a context that
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1676 permits the web server to modify and create files. If you're using the
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1677 mysql or postgresql backend you may also need to update your policy to
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1678 allow the web server to access the database socket.
9f4dd27ae843 documentation cleanup from Luke Ross (patch [SF#1594860])
Richard Jones <richard@users.sourceforge.net>
parents: 3736
diff changeset
1679
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1680
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3814
diff changeset
1681 Public Tracker Considerations
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1682 =============================
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3814
diff changeset
1683
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3814
diff changeset
1684 If you run a public tracker, you will eventually have to think about
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3814
diff changeset
1685 dealing with spam entered through both the web and mail interfaces.
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3814
diff changeset
1686
5300
d8ed32b297e2 Update to migrating backend and tweak to install doc.
John Rouillard <rouilj@ieee.org>
parents: 5140
diff changeset
1687 See the section on `Preventing SPAM`_ in the
d8ed32b297e2 Update to migrating backend and tweak to install doc.
John Rouillard <rouilj@ieee.org>
parents: 5140
diff changeset
1688 `customisation documentation`_ that has a simple detector
d8ed32b297e2 Update to migrating backend and tweak to install doc.
John Rouillard <rouilj@ieee.org>
parents: 5140
diff changeset
1689 that will block lot of spam attempts.
3830
a48c514c465f Add simple anti-spam recipe to docs
Richard Jones <richard@users.sourceforge.net>
parents: 3814
diff changeset
1690
7501
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1691 Also you can consider adding `reCaptcha to reduce bot logins as
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1692 described on the wiki
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1693 <https://wiki.roundup-tracker.org/RequireReCAPTCHAForLogin>`_. The
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1694 wiki also documents how to add `multi-factor (MFA)/one time
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1695 keys/password using TOTP/HOTP
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1696 <https://wiki.roundup-tracker.org/OneTimePasswords>`_. If you
7602
4778b8f8f301 docs: fix grammar
John Rouillard <rouilj@ieee.org>
parents: 7601
diff changeset
1697 have a single sign on system see: the `wiki page on using Shibboleth
7501
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1698 <https://wiki.roundup-tracker.org/ShibbolethLogin>`_
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1699 or `LDAP <https://wiki.roundup-tracker.org/LDAPLogin2_1_5_1>`_
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1700 with Roundup. More customisation can be found under the
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1701 Security headings of the `CustomisationExamples wiki page
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1702 <https://wiki.roundup-tracker.org/CustomisationExamples>`_ and
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1703 `AdminstrationExample
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1704 <https://wiki.roundup-tracker.org/AdministrationExample>`_ pages
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1705 on the wiki.
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1706
d401d6f51604 Update Public tracker consideration with wiki links
John Rouillard <rouilj@ieee.org>
parents: 7500
diff changeset
1707
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1708 Docker Support
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1709 ==============
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1710
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1711 If you don't want to install Roundup on a host, you can create a
7500
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1712 Docker container or use the `pre-built container on
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1713 hub.docker.com
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1714 <https://hub.docker.com/r/rounduptracker/roundup>`_. Docker hub
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1715 images support `multiple tags <#tags-for-dockerhub-docker-images>`_.
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1716 Docker images run Roundup using the `stand-alone web
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1717 server`_ method. The image only supports http. We suggest putting an
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1718 https terminating proxy in front of it.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1719
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1720 This is a work in progress and patches to improve it are welcome. You
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1721 can find the docker config files under the `scripts/Docker` directory
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1722 of the source tree.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1723
7500
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1724 The Roundup container uses the 64 bit Alpine Python distribution.
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1725 It includes database drivers for anydbm, SQLite, MySQL and
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1726 Postgresql (Postgresql is untested). It also includes additional
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1727 libraries that are listed in `scripts/Docker/requirements.txt`
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
1728 (including redis client support).
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1729
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1730 Email support is a work in progress. Outgoing email to an external
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1731 SMTP server should work. Receiving email should work by using a
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1732 scheduled (cron) job to access email:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1733
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1734 * `As a regular job using a mailbox source`_
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1735 * `As a regular job using a POP source`_
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1736 * `As a regular job using an IMAP source`_
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1737
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1738 However running cron in a container is problematic (running
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1739 busybox crond as root vs. non-root, requiring setgrp privs
7603
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1740 etc).
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1741
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1742 Using the host's crontab with a command like::
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1743
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1744 docker exec roundup-tracker roundup-mailgw tracker \
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1745 mailbox /var/spool/mail/roundup
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1746
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1747 might be a solution if you can mount a mail spool directory or use
7515d03fb26d docs: add possible way to get email into dockerized roundup.
John Rouillard <rouilj@ieee.org>
parents: 7602
diff changeset
1748 pop/imap. Patches for implementing better email support are welcome.
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1749
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1750 If you want to use a MySQL backend, see `Docker-compose
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1751 Deployment`_ to deploy a Roundup container and a MySQL container
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1752 backend for use with Roundup.
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1753
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1754 We recommend you follow the `OSWAP Docker Security practices`_ for your
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1755 production Roundup instance.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1756
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1757 .. _OSWAP Docker Security practices:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1758 https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1759
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1760 Building a Docker Container
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1761 ---------------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1762
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1763 You can build a docker container in one of 4 modes defined by the
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1764 ``source`` build-arg.
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1765
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1766 ``--build-arg="source=local"``
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1767 the default if no source is defined. Build using the version in
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1768 the source tree by running ``setup.py install``.
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1769
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1770 ``--build-arg="source=pypi"``
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1771 build the newest production release version deployed to pypi.
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1772 If you want to build using a pre-release, you can append
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1773 `pip version specifiers
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1774 <https://peps.python.org/pep-0440/#version-specifiers>`_ to
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1775 `pypi` without embedding any spaces. For example::
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1776
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1777 # install 2.2.0 if available or 2.2.0b1 or 2.2.0b2 etc.
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1778 --build-arg="source=pypi~=2.2.0b1"
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1779
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1780 # install only a 2.2.0 beta
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1781 --build-arg="source=pypi~=2.2.0b1,!=2.2.0"
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1782
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1783 Note that versions of Roundup before 2.2 may not run correctly
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1784 in a Docker container.
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1785
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1786 ``--build-arg="source=pip_local"``
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1787 Build using the version in the source tree by running ``pip
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1788 install``. This places some files (e.g. man pages, templates) in
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1789 different directories from the `local` install but is preferred
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1790 by some Python users.
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1791
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1792 ``--build-arg="source=pip_sdist"``
7659
e9a2b74150bd Update doc on --build-arg="source=pip_sdist" for docker.
John Rouillard <rouilj@ieee.org>
parents: 7643
diff changeset
1793 Disabled - hopefully it will be available in the future.
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1794 This is meant for maintainer/developer use. It installs using
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1795 pip from a source distribution (sdist) tarball built by
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1796 following the RELEASE.txt. It is meant for testing
7659
e9a2b74150bd Update doc on --build-arg="source=pip_sdist" for docker.
John Rouillard <rouilj@ieee.org>
parents: 7643
diff changeset
1797 releases or building a docker image that installs a new pending
e9a2b74150bd Update doc on --build-arg="source=pip_sdist" for docker.
John Rouillard <rouilj@ieee.org>
parents: 7643
diff changeset
1798 source distribution release. Normal users/admins should not use it.
e9a2b74150bd Update doc on --build-arg="source=pip_sdist" for docker.
John Rouillard <rouilj@ieee.org>
parents: 7643
diff changeset
1799 Use ``local`` or ``pip_local`` instead.
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1800
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1801 Build a docker container using the code in the current directory,
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1802 with this build command from the top of the source tree::
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1803
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1804 docker build -t roundup-app -f scripts/Docker/Dockerfile .
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1805
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1806 Build a container using the newest production (non pre-release)
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1807 Roundup release on PyPI, by running::
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1808
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1809 docker build -t roundup-app --build-arg="source=pypi" \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1810 -f scripts/Docker/Dockerfile .
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1811
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1812 Change the ``build-arg`` for building in other modes.
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1813
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1814 The Dockerfile declares a single volume mounted at
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1815 ``/usr/src/app/tracker`` inside the container. You will mount
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1816 your tracker home directory at this location. The
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1817 ``/usr/src/app`` path can be changed by adding::
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1818
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1819 --build-arg="appdir=/new/path"
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1820
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1821 You can also add additional modules to the docker container by
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1822 using::
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1823
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1824 --build-arg="pip_mod=requests setproctitle"
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1825
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1826 Because of deficiencies in the docker program (see:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1827 https://github.com/moby/moby/issues/29110#issuecomment-1100676306),
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1828 there is no way to determine the version of Python inside the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1829 container and make that available as part of the build process. If
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1830 your build fails because the ``pythonversion does not match``, add the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1831 suggested ``--build-arg`` to the ``docker build`` command line.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1832
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1833 .. _UID at image build time:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1834
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1835 By default the container runs Roundup using UID 1000. By setting
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1836 ``--build-arg="roundup_uid=2000"`` you can change the UID and
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
1837 GID.
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1838
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1839 Configuring Roundup in the Container
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1840 ------------------------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1841
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1842 .. caution::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1843
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1844 Docker modifies iptables firewall rules. This allows access to the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1845 container from your local network. `See the official documentation
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1846 for details
8060
f53fd57a0cf3 docs: update link to docker publish command.
John Rouillard <rouilj@ieee.org>
parents: 8054
diff changeset
1847 <https://docs.docker.com/reference/cli/docker/container/run/#publish>`_.
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1848 UFW rules are known to be be ignored (see:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1849 https://github.com/moby/moby/issues/4737). Use ``-p
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1850 127.0.0.1:ext_port:container_port`` in your docker run commands or
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1851 implement suggestions like: https://github.com/chaifeng/ufw-docker.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1852
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1853 Once the docker image is created using one of the build commands
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1854 above, run an interactive session with::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1855
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1856 docker run -it --rm -p 127.0.0.1:9017:8080 \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1857 -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1858
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1859 The ``-v`` option maps a directory from the host into the docker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1860 container. Note that uid 1000 is used by roundup by default. The uid
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1861 of the directory (and all files under it) must match the uid. You can
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1862 set the `UID at image build time`_. This
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1863 example assumes your tracker configs are in the tracker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1864 subdirectory. Replace ``$PWD/tracker`` with the full path name to the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1865 directory where the tracker home(s) are to be stored.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1866
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1867 The ``-p`` option maps an external port (9017) to proxy the roundup
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1868 server running at port 8080 to the outside. Note if you remove
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1869 ``127.0.0.1:`` from the -p argument, *any host* on the network will be
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1870 able to access the tracker at port 9017.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1871
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1872 If the tracker directory is empty, the docker container will prompt
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1873 you to `install a tracker template`_ (step 3) and prompt you for the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1874 database type.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1875
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1876 .. _install a tracker template: #configuring-your-first-tracker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1877
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1878 Then you need to configure the tracker by editing
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1879 ``template/config.ini``. Make sure that the tracker web setting ends
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1880 in ``/issues/`` See `Configuring your first tracker`_ and the top of
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1881 ``config.ini`` for other settings.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1882
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1883 Once you have configured the tracker, run another interactive session
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1884 to `initialise the tracker`_ (step 4) with::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1885
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1886 docker run -it --rm -p 127.0.0.1:9017:8080 \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1887 -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1888
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1889 this will initialise the database and attempt to start the server. If
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1890 that is successful, use control-c to exit the server.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1891
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1892 .. _initialise the tracker: #configuring-your-first-tracker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1893
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1894 Now start the server non-interactively (note no `-it` option) with::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1895
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1896 docker run -p 9017:8080 -d \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1897 -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1898
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1899 Your tracker will be available at: ``http://yourhost:9017/issues/``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1900
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1901 If you need to access your container while the server is running you
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1902 can use::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1903
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1904 docker exec -it c0d5 sh
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1905
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1906 where ``c0d5`` is the id prefix for the running container obtained
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1907 from ``docker container ls``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1908
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1909 You should place a web server in front of Roundup (in reverse proxy
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1910 mode) for production use. See the proxy_pass example below:
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1911
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1912 * `Nginx HTTP Server`_
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1913
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1914 You can expose the port directly to your intranet by removing ``127.0.0.1``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1915 from the ``-p`` option. See `Stand-alone Web Server`_ for more details.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1916
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1917
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1918 Running Your Container
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1919 ----------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1920
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1921 .. note::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1922 The examples below use the locally built docker container
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1923 specification: ``roundup-app``. You can replace it with the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1924 docker hub specification ``rounduptracker/roundup:latest``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1925 (provided latest is newer than 2.3.0).
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1926
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1927 As of version 2.3.0 the Docker container has multiple entry points.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1928
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1929 Guided install
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1930 ~~~~~~~~~~~~~~
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1931
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1932 By default, running::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1933
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1934 docker run -it --rm -p 127.0.0.1:9017:8080 \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1935 -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1936
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1937 3 times will install, initialize and serve a Roundup tracker at
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1938 ``..../issues/`` using ``$PWD/tracker`` as the tracker home. This is the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1939 "guided install" method described in `Configuring Roundup in the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1940 Container`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1941
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1942 Arguments for roundup-server
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1943 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1944
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1945 Once you have initialized your tracker, any arguments placed at the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1946 end of the ``docker run`` command are passed to the ``roundup-server``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1947 These arguments **replace** the default arguments of ``issues=tracker``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1948
7707
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1949 Brief Help
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1950 ~~~~~~~~~~
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1951
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1952 You can get help running the docker image::
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1953
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1954 docker run -it \
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1955 -v $PWD/tracker:/usr/src/app/tracker \
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1956 roundup-app:latest help
36c3acb4b49b feat: add help argument for docker image
John Rouillard <rouilj@ieee.org>
parents: 7700
diff changeset
1957
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1958 Invoking a Shell
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1959 ~~~~~~~~~~~~~~~~
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1960
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1961 You can invoke a shell inside the container without exec'ing into the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1962 container using::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1963
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1964 docker run -it \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1965 -v $PWD/tracker:/usr/src/app/tracker \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1966 roundup-app:latest shell
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1967
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1968 Then you can manually configure your tracker using ``roundup-admin -i
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1969 tracker`` using the directions for `Configuring your first tracker`_.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1970 This is also how you would access tools like ``roundup-gettext`` which
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1971 do not have direct entry points like ``admin`` for ``roundup-admin``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1972 and ``demo`` for ``roundup-demo``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1973
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1974 Invoke roundup-admin
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1975 ~~~~~~~~~~~~~~~~~~~~
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1976
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1977 You can run ``roundup-admin`` directly by using::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1978
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1979 docker run -it \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1980 -v $PWD/tracker:/usr/src/app/tracker \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1981 roundup-app:latest admin -i tracker/tracker1
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1982
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1983 to start ``roundup-admin`` using the directory
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1984 ``$PWD/tracker/tracker1``. This is one way to create multiple trackers
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1985 in subdirectories. It is no different from starting a shell and
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1986 invoking ``roundup-admin`` manually.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1987
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1988 One possibly useful command is::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1989
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1990
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1991 docker run -it \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1992 -v $PWD/tracker:/usr/src/app/tracker \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1993 roundup-app:latest admin templates
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1994
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1995 to list description of all the installed templates.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1996
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1997 Invoke roundup-demo
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1998 ~~~~~~~~~~~~~~~~~~~
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
1999
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2000 Lastly you can::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2001
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2002 docker run -it -p 127.0.0.1:8917:8080 \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2003 -v $PWD/tracker:/usr/src/app/tracker \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2004 roundup-app:latest demo anydbm responsive
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2005
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2006 to create a directory ``$PWD/tracker/demo`` and autoconfigure a server
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2007 using the anydbm backend based on the responsive tracker template.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2008 See `demo mode using docker`_ for steps to change the server port.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2009
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2010 Debugging
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2011 ~~~~~~~~~
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2012
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2013 If you add ``-e SHELL_DEBUG=1`` to the docker command, it sets the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2014 ``SHELL_DEBUG`` environment variable which will enable debugging
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2015 output from the startup script.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2016
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2017 Running Multiple Trackers
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2018 --------------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2019
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2020 If you want to run multiple trackers, create a subdirectory for each
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2021 tracker home under the volume mount point (``$PWD/tracker``). Then
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2022 invoke ``docker run`` passing the roundup-server tracker
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2023 specifications like::
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2024
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2025 docker run --rm -p 9017:8080 \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2026 -v /.../issue.tracker:/usr/src/app/tracker \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2027 roundup-app:latest tracker1=tracker/tracker1_home \
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2028 tracker2=tracker/tracker2_home
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2029
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2030 This will set up two trackers that can be reached at
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2031 ``http://yourhost:9017/tracker1/`` and
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2032 ``http://yourhost:9017/tracker2/``. The arguments after
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2033 ``roundup-app:latest`` are arguments including tracker paths that are
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2034 passed to ``roundup-server``.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2035
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2036 Docker-compose Deployment
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2037 -------------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2038
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2039 If you want to run using the mysql backend, you can use docker-compose
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2040 with ``scripts/Docker/docker-compose.yml``. This will run Roundup and
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2041 MySQL in containers. Directions for building using docker-compose are
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2042 at the top of the yml file.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2043
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2044 Tags for Dockerhub Docker Images
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2045 --------------------------------
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2046
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2047 The docker images available from
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2048 https://hub.docker.com/r/rounduptracker/roundup are tagged with:
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2049 version-build, version, and ``latest`` tags. Only production
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2050 releases (not pre-releases) are tagged this way. For example, the
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2051 tags when 2.3.0 is released will be:
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2052
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2053 ``rounduptracker/roundup:latest``
7500
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2054 is a moving tag that tracks the latest build with the newest
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2055 production version of Roundup using the current newest Alpine
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2056 release with the versions of Python packages at the time of
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2057 the build.
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2058
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2059 ``rounduptracker/roundup:2.3.0``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2060 is a moving tag that tracks the latest build
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2061 of version 2.3.0 of Roundup. The Roundup software in this
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2062 build will match the 2.3.0 version released on PyPi, but the
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2063 underlying Alpine image or versions of the supporting Python
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2064 libraries (redis, xapian, psycopg2, ...) will change.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2065
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2066 ``rounduptracker/roundup:2.3.0-1``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2067 is a static tag and marks the first build of the version
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2068 2.3.0 docker image. When a new release of the image is done,
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2069 it will get the tag ``2.3.0-2`` etc. This is an alternative to
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2070 pulling using a sha256 sum. However it is possible to
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2071 overwrite this image/tag. So it **does not** provide the same
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2072 security guarantees that using a sha256 sum does.
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2073
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2074 In addition to the release tags, there may be one or more
7531
913a73b9fab5 Update for 2.3.0 release
John Rouillard <rouilj@ieee.org>
parents: 7524
diff changeset
2075 development tags available. All tags will include `devel`. For
7441
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2076 example: ``rounduptracker/roundup:2.3.0b1-devel``,
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2077 ``rounduptracker/roundup:devel``
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2078
e7df82ae137d Cleanup docker before 2.3.0b1 release
John Rouillard <rouilj@ieee.org>
parents: 7438
diff changeset
2079 You should not assume that any ``devel`` tag is static. They are
7500
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2080 mainly for use by Roundup developers/maintainers/testers for
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2081 testing. There may be alternate tags ending with ``-devel`` to
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2082 indicate builds from specific Mercurial versions/hashes. Also the
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2083 tag may be overwritten to change the underlying Python libraries
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2084 or images. Unless you like the bleeding edge, these should
c550b338616a Link to docker support from main web index. Docker support changes.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
2085 **not** be used in production.
2069
d8c7fd205cd8 info for installing the CSV module
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
2086
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
2087 Maintenance
Richard Jones <richard@users.sourceforge.net>
parents: 1227
diff changeset
2088 ===========
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2089
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2090 Read the `Tasks section of the administration guide
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2091 <admin_guide.html#tasks>`_ for information about how to perform
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2092 common maintenance tasks on Roundup.
1049
Richard Jones <richard@users.sourceforge.net>
parents: 1024
diff changeset
2093
782
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
2094
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
2095 Upgrading
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
2096 =========
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
2097
882
b99948d32a2d clearing up ambiguous ref name
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
2098 Read the separate `upgrading document`_, which describes the steps needed to
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
2099 upgrade existing tracker trackers for each version of Roundup that is
782
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
2100 released.
6f6eb43d9d86 Moved the MIGRATION text in with the rest of the docco, fixed up for 0.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
2101
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2102
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2103 Further Reading
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2104 ===============
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2105
3528
762d65fefea5 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 3524
diff changeset
2106 If you intend to use Roundup with anything other than the default
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2107 templates, if you would like to hack on Roundup, or if you would
7354
692242b3effd initial pass to change references to reference doc where needed.
John Rouillard <rouilj@ieee.org>
parents: 7350
diff changeset
2108 like implementation details, you should read `Customising
692242b3effd initial pass to change references to reference doc where needed.
John Rouillard <rouilj@ieee.org>
parents: 7350
diff changeset
2109 Roundup`_ and the `Roundup reference`_.
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2110
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2111
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2112 Running Multiple Trackers
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2113 =========================
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2114
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2115 Things to think about before you jump off the deep end and install
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2116 multiple trackers, which involve additional URLs, user databases, email
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2117 addresses, databases to back up, etc.
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2118
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2119 1. Do you want a tracker per product you sell/support? You can just add
2161
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2120 a new property to your issues called Product, and filter by that. See
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2121 the customisation example `adding a new field to the classic schema`_.
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2122 2. Do you want to track internal software development issues and customer
2186
3f89c8ffe4f1 version info in scripts
Richard Jones <richard@users.sourceforge.net>
parents: 2179
diff changeset
2123 support issues separately? You can just set up an additional "issue"
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2124 class called "cust_issues" in the same tracker, mimicing the normal
2161
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2125 "issue" class, but with different properties. See the customisation
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2126 example `tracking different types of issues`_.
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2127
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2128
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2129 Platform-Specific Notes
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2130 =======================
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2131
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2132
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2133 Windows
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2134 -------
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2135
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2136 .. index:: windows; choose non-default session/otk database
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2137
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2138 Configure session database
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2139 ~~~~~~~~~~~~~~~~~~~~~~~~~~
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2140
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2141 By default the session and one time key (OTK) databases default to
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2142 using anydbm as the session store. Because GNU dbm and Ndbm are
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2143 available on Linux, this is a reasonable default. However Windows
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2144 doesn't have compiled libraries for these databases. So it defaults to
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2145 "dumb" dbm which is written in Python and is slow. So we recommend
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2146 using `some other backend for your session database`_. SQLite or Redis
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2147 can be used if you don't want to run a separate supported RDBMS
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2148 database server.
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2149
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2150 .. index:: windows; add Roundup to path
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2151
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2152 Windows command-line tools
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2153 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2154
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2155 To make the command-line tools accessible in Windows, you need to update
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2156 the "Path" environment variable in the Registry via a dialog box.
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2157
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2158 On Windows 2000 and later:
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2159
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2160 1) Press the "Start" button.
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2161 2) Choose "Settings"
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2162 3) Choose "Control Panel"
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2163 4) Choose "System"
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2164 5) Choose "Advanced"
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2165 6) Choose "Environmental Variables"
1746
9c1da921cd35 minor rest tweak
Richard Jones <richard@users.sourceforge.net>
parents: 1688
diff changeset
2166 7) Add: "<dir>\Scripts" to the "Path" environmental variable.
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2167
6727
3f3ce3004013 issue2551206 - remove mention of roundup installer, fix up windows docs
John Rouillard <rouilj@ieee.org>
parents: 6663
diff changeset
2168 Where <dir> in 7) is the root directory (e.g., ``C:\Python27\Scripts``)
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2169 of your Python installation.
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2170
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2171 I understand that in XP, 2) above is not needed as "Control
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2172 Panel" is directly accessible from "Start".
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2173
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2174 I do not believe this is possible to do in previous versions of Windows.
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2175
7608
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2176 Use pip to install pyreadline3 for roundup-admin line editing
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2177
7608
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2178
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2179 If you install pyreadline3_ using pip, roundup-admin will support
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2180 command line editing and history.
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2181
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2182 This will remove the dreaded::
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2183
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2184 Note: command history and editing not available
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2185
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2186 warning when starting roundup-admin.
1649
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2187
6d392197daa3 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 1648
diff changeset
2188 Windows Server
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2189 ~~~~~~~~~~~~~~
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2190
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2191 To have the Roundup web server start up when your machine boots up, there
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2192 are two different methods, the scheduler and installing the service.
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2193
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2194 .. index:: windows; use scheduler for email integration
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2195
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2196 .. _Using the Windows scheduler:
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2197
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2198 1. Using the Windows scheduler
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2199 ''''''''''''''''''''''''''''''
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2200
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2201 Set up the following in Scheduled Tasks (note, the following is for a
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2202 cygwin setup):
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2203
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2204 Run
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2205 ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2206
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2207 Start In
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2208 ``C:\cygwin\opt\roundup\bin``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2209
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2210 Schedule
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2211 At System Startup
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2212
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2213 To have the Roundup mail gateway run periodically to poll a POP email address,
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2214 set up the following in Scheduled Tasks:
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2215
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2216 Run
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2217 ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2218
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2219 Start In
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2220 ``C:\cygwin\opt\roundup\bin``
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2221
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2222 Schedule
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2223 Every 10 minutes from 5:00AM for 24 hours every day
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2224
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2225 Stop the task if it runs for 8 minutes
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2226
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2227
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2228 .. index:: windows; setup Roundup a service
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2229
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2230 2. Installing the roundup server as a Windows service
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2231 '''''''''''''''''''''''''''''''''''''''''''''''''''''
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2232
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2233 This is more Windows oriented and will make the Roundup server run as
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2234 soon as the PC starts up without any need for a login or such. It will
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2235 also be available in the normal Windows Administrative Tools.
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2236
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2237 For this you need first to create a service ini file containing the
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2238 relevant settings.
1588
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1576
diff changeset
2239
3797
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2240 1. It is created if you execute the following command from within the
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2241 scripts directory (notice the use of backslashes)::
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2242
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2243 roundup-server -S -C <trackersdir>\server.ini -n <servername> -p 8080 -l <trackersdir>\trackerlog.log software=<trackersdir>\Software
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2244
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2245 where the item ``<trackersdir>`` is replaced with the physical directory
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2246 that hosts all of your trackers. The ``<servername>`` item is the name
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2247 of your roundup server PC, such as w2003srv or similar.
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2248
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2249 2. Next open the now created file ``C:\DATA\roundup\server.ini`` file
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2250 (if your ``<trackersdir>`` is ``C:\DATA\roundup``).
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2251 Check the entries for correctness, especially this one::
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2252
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2253 [trackers]
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2254 software = C:\DATA\Roundup\Software
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2255
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2256 (this is an example where the tracker is named software and its home is
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2257 ``C:\DATA\Roundup\Software``)
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2258
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2259 3. Next give the commands that actually installs and starts the service::
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2260
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2261 roundup-server -C C:\DATA\Roundup\server.ini -c install
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2262 roundup-server -c start
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2263
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2264 4. Finally open the AdministrativeTools/Services applet and locate the
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2265 Roundup service entry. Open its properties and change it to start
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2266 automatically instead of manually.
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2267
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2268 If you are using Apache as the webserver you might want to use it with
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2269 mod_python instead to serve out Roundup. In that case see the mod_python
bb6e8fafa341 Updated Windows installation docs (thanks Bo Berglund)
Richard Jones <richard@users.sourceforge.net>
parents: 3794
diff changeset
2270 instructions above for details.
1576
80519db85eac More tweaks to the licensing to make the Debian folks happy :)
Richard Jones <richard@users.sourceforge.net>
parents: 1574
diff changeset
2271
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2272 Linux
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2273 -----
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2274
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2275 Make sure you read the instructions under `UNIX environment steps`_.
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2276
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2277 Sendmail smrsh
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2278 ~~~~~~~~~~~~~~
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2279
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2280 If you use Sendmail's ``smrsh`` mechanism, you will need to tell
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2281 smrsh that roundup-mailgw is a valid/trusted mail handler
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2282 before it will work.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2283
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2284 This is usually done via the following 2 steps:
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2285
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2286 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2287 which points to the full path of your actual ``roundup-mailgw``
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2288 script.
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2289
1089
43ab730ee194 instance -> tracker, node -> item
Richard Jones <richard@users.sourceforge.net>
parents: 1078
diff changeset
2290 2. change your alias to ``"|roundup-mailgw <tracker_home>"``
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2291
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2292
1574
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
2293
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
2294 Solaris
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
2295 -------
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
2296
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
2297 You'll need to build Python.
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
2298
1939
1303c208419d some updates that were sitting on disk
Richard Jones <richard@users.sourceforge.net>
parents: 1913
diff changeset
2299 Make sure you read the instructions under `UNIX environment steps`_.
1303c208419d some updates that were sitting on disk
Richard Jones <richard@users.sourceforge.net>
parents: 1913
diff changeset
2300
1574
67af854f4c33 more installation hintage
Richard Jones <richard@users.sourceforge.net>
parents: 1571
diff changeset
2301
2972
dd558120d927 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2945
diff changeset
2302 Problems? Testing your Python...
dd558120d927 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2945
diff changeset
2303 ================================
dd558120d927 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2945
diff changeset
2304
dd558120d927 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2945
diff changeset
2305 .. note::
6297
a635a60ffb84 Remove standalone pytest run_tests.py bundle
John Rouillard <rouilj@ieee.org>
parents: 6265
diff changeset
2306 The ``run_tests.py`` script is not packaged in Roundup's source
7580
13af5f28207d docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7562
diff changeset
2307 distribution anymore. You should install:
7581
9dd27f40de4c docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7580
diff changeset
2308
9dd27f40de4c docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7580
diff changeset
2309 * pytest,
9dd27f40de4c docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7580
diff changeset
2310 * requests, and
9dd27f40de4c docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7580
diff changeset
2311 * mock
9dd27f40de4c docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7580
diff changeset
2312
7580
13af5f28207d docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7562
diff changeset
2313 using your distributions package manger or using pip/pip2/pip3 to
7581
9dd27f40de4c docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7580
diff changeset
2314 install pytest etc. for your Python version. See the
9dd27f40de4c docs: document dependencies required for testing
John Rouillard <rouilj@ieee.org>
parents: 7580
diff changeset
2315 `administration guide`_ for details.
2972
dd558120d927 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2945
diff changeset
2316
4317
15834821b8c7 - fix explicit python version description...
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4315
diff changeset
2317 Remember to have a database user 'rounduptest' prepared (with
15834821b8c7 - fix explicit python version description...
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4315
diff changeset
2318 password 'rounduptest'). This user
4315
cfb01b2bc730 Fix documentation on user required to run the tests, fixes issue2550618.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4249
diff changeset
2319 must have at least the rights to create and drop databases.
cfb01b2bc730 Fix documentation on user required to run the tests, fixes issue2550618.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4249
diff changeset
2320 Documentation: details on `adding MySQL users`_,
cfb01b2bc730 Fix documentation on user required to run the tests, fixes issue2550618.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4249
diff changeset
2321 for PostgreSQL you want to call the ``createuser`` command with the
cfb01b2bc730 Fix documentation on user required to run the tests, fixes issue2550618.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4249
diff changeset
2322 ``-d`` option to allow database creation.
cfb01b2bc730 Fix documentation on user required to run the tests, fixes issue2550618.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4249
diff changeset
2323
7374
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
2324 This can only be done if you `install the source`_ distribution
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
2325 (steps 1-3) or from a `mercurial checkout
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
2326 <../code.html#get-sources>`_. It will not work if you used `pip
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
2327 install` as the test suite is not installed. Once you've unpacked
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
2328 roundup's source, if you have pytest installed, run ``python -m
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
2329 pytest test`` in the Roundup source directory and make sure there
72de757edf78 issue2551220 - In installation.txt clarify source directory.
John Rouillard <rouilj@ieee.org>
parents: 7354
diff changeset
2330 are no errors. If there are errors, please let us know!
2972
dd558120d927 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2945
diff changeset
2331
7399
deb8e7e6d66d Skip redis tests if unable to communicate with the server.
John Rouillard <rouilj@ieee.org>
parents: 7374
diff changeset
2332 Note that redis tests uses database 15 of the redis server running on
deb8e7e6d66d Skip redis tests if unable to communicate with the server.
John Rouillard <rouilj@ieee.org>
parents: 7374
diff changeset
2333 localhost.The tests verify that the database is empty before the redis
deb8e7e6d66d Skip redis tests if unable to communicate with the server.
John Rouillard <rouilj@ieee.org>
parents: 7374
diff changeset
2334 tests start. If you use a password on your redis database it can be
deb8e7e6d66d Skip redis tests if unable to communicate with the server.
John Rouillard <rouilj@ieee.org>
parents: 7374
diff changeset
2335 specified in the ``pytest_redis_pw`` environment variable when you run
deb8e7e6d66d Skip redis tests if unable to communicate with the server.
John Rouillard <rouilj@ieee.org>
parents: 7374
diff changeset
2336 the test.
deb8e7e6d66d Skip redis tests if unable to communicate with the server.
John Rouillard <rouilj@ieee.org>
parents: 7374
diff changeset
2337
1287
5402a6f2a754 Added quotes around python interpreter in windows bat [SF#623963]
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
2338 .. _`user guide`: user_guide.html
4949
c3a90535f7a7 Backed out changeset 4a3a35192ad1
John Rouillard <rouilj@ieee.org>
parents: 4948
diff changeset
2339 .. _`roundup specification`: spec.html
7354
692242b3effd initial pass to change references to reference doc where needed.
John Rouillard <rouilj@ieee.org>
parents: 7350
diff changeset
2340 .. _`tracker configuration`: reference.html#tracker-configuration
1245
d8c98af869ff merge from maint-0-5
Richard Jones <richard@users.sourceforge.net>
parents: 1244
diff changeset
2341 .. _`customisation documentation`: customizing.html
7354
692242b3effd initial pass to change references to reference doc where needed.
John Rouillard <rouilj@ieee.org>
parents: 7350
diff changeset
2342 .. _`Roundup reference`: reference.html
692242b3effd initial pass to change references to reference doc where needed.
John Rouillard <rouilj@ieee.org>
parents: 7350
diff changeset
2343 .. _`reference documentation`: reference.html
5300
d8ed32b297e2 Update to migrating backend and tweak to install doc.
John Rouillard <rouilj@ieee.org>
parents: 5140
diff changeset
2344 .. _`preventing spam`: customizing.html#preventing-spam
2161
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2345 .. _`Adding a new field to the classic schema`:
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2346 customizing.html#adding-a-new-field-to-the-classic-schema
7887
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2347 .. _`some other backend for your session database`:
35b4049ea2ad doc: fix platform notes hierarchy; don't use anydbm session db
John Rouillard <rouilj@ieee.org>
parents: 7863
diff changeset
2348 admin_guide.html#configuring-session-databases
2161
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2349 .. _`Tracking different types of issues`:
98656054ccfa *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2069
diff changeset
2350 customizing.html#tracking-different-types-of-issues
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2351 .. _`customising roundup`: customizing.html
882
b99948d32a2d clearing up ambiguous ref name
Richard Jones <richard@users.sourceforge.net>
parents: 798
diff changeset
2352 .. _`upgrading document`: upgrading.html
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents: 1965
diff changeset
2353 .. _`administration guide`: admin_guide.html
7340
7b9bddda9d2d Add support for demo mode in docker.
John Rouillard <rouilj@ieee.org>
parents: 7316
diff changeset
2354 .. _`What does Roundup install`: admin_guide.html#what-does-roundup-install
6663
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
2355 .. _`doc/postgresql.txt`: postgresql.html
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
2356 .. _`doc/mysql.txt`: mysql.html
2554
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
2357
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
2358
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
2359 .. _External hyperlink targets:
52944e87909c added mod_python setup example
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2449
diff changeset
2360
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2361
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2362
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2363 .. _`adding MySQL users`:
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2364 https://dev.mysql.com/doc/refman/8.0/en/creating-accounts.html
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2365 .. _apache: https://httpd.apache.org/
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
2366 .. _brotli: https://pypi.org/project/Brotli/
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2367 .. _docutils: https://pypi.org/project/docutils/
5337
01dabc0483b0 more changes to prep for 1.6 release.
John Rouillard <rouilj@ieee.org>
parents: 5321
diff changeset
2368 .. _flup: https://pypi.org/project/flup/
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2369 .. _gpg: https://www.gnupg.org/software/gpgme/index.html
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2370 .. _jinja2: https://palletsprojects.com/p/jinja/
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2371 .. _markdown: https://python-markdown.github.io/
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2372 .. _markdown2: https://github.com/trentm/python-markdown2
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2373 .. _mistune: https://pypi.org/project/mistune/
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2374 .. _mod_python: https://github.com/grisha/mod_python
5891
6e341009593b Deprecate mod_python issue2551005
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
2375 .. _mod_wsgi: https://pypi.org/project/mod-wsgi/
5510
e2978ed3b550 update link to new mysqlclient module and recommend update in upgrading.txt
Christof Meerwald <cmeerw@cmeerw.org>
parents: 5494
diff changeset
2376 .. _MySQLdb: https://pypi.org/project/mysqlclient/
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2377 .. _Olson tz database: https://www.iana.org/time-zones
6663
e63f514bb0e6 issue2551201 - Update references to psycopg2
John Rouillard <rouilj@ieee.org>
parents: 6653
diff changeset
2378 .. _Psycopg2: https://www.psycopg.org/
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2379 .. _pyjwt: https://pypi.org/project/PyJWT/
6419
4d321d52d67d fix broken link for pyopenssl
John Rouillard <rouilj@ieee.org>
parents: 6391
diff changeset
2380 .. _pyopenssl: https://pypi.org/project/pyOpenSSL/
7608
cdc7490f510e docs: add mention of pyreadline3 under windows
John Rouillard <rouilj@ieee.org>
parents: 7603
diff changeset
2381 .. _pyreadline3: https://pypi.org/project/pyreadline3/
5756
e48b039b0ec0 issue2550966: fix suboptimal links in docs.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
2382 .. _pysqlite: https://pysqlite.org/
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2383 .. _pytz: https://pypi.org/project/pytz/
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2384 .. _pywin32: https://pypi.org/project/pywin32/
6814
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
2385 .. _Redis: https://redis.io
3f60a71b0812 Summary: Support selecion session/otk data store. Add redis as data store.
John Rouillard <rouilj@ieee.org>
parents: 6797
diff changeset
2386 .. _redis-py: https://pypi.org/project/redis/
7065
48da482d7d93 reference requests library for imap_oauth in roundup-mailgw
John Rouillard <rouilj@ieee.org>
parents: 7042
diff changeset
2387 .. _requests: https://requests.readthedocs.io/en/latest/
7348
2c5af1c920fc replace whoosh link original was a redirect.
John Rouillard <rouilj@ieee.org>
parents: 7347
diff changeset
2388 .. _Whoosh: https://whoosh.readthedocs.io/en/latest/
6391
205bc1d27985 Added links for pyjwt, markdown libs, rearranged links.
John Rouillard <rouilj@ieee.org>
parents: 6390
diff changeset
2389 .. _Xapian: https://xapian.org/
6458
8f1b91756457 issue2551147 - Enable compression of http responses in roundup.
John Rouillard <rouilj@ieee.org>
parents: 6419
diff changeset
2390 .. _zstd: https://pypi.org/project/zstd/
Roundup Issue Tracker: http://roundup-tracker.org/