Mercurial > p > roundup > code

comparison doc/installation.txt @ 1221:778297033003

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cleanup of install docco
author Richard Jones <richard@users.sourceforge.net>
date Thu, 26 Sep 2002 03:03:50 +0000
parents 4c9882cb16a3
children 92d8e1aad2e9
comparison
equal deleted inserted replaced
1220:953279b8b32f 1221:778297033003
1 ================== 1 ==================
2 Installing Roundup 2 Installing Roundup
3 ================== 3 ==================
4 4
5 :Version: $Revision: 1.25 $ 5 :Version: $Revision: 1.26 $
6 6
7 .. contents:: 7 .. contents::
8 8
9 9
10 Overview 10 Overview
11 ======== 11 ========
12 12
13 Broken out separately, there are several conceptual pieces to a 13 Broken out separately, there are several conceptual pieces to a
14 Roundup installation: 14 Roundup installation:
15
16 Roundup trackers
17 Trackers consist of issues (be they bug reports or otherwise), tracker
18 configuration file(s), web HTML files etc. Roundup trackers are initialised
19 with a "Template" which defines the fields usable/assignable on a
20 per-issue basis. Descriptions of the provided templates are given in
21 `choosing your template`_.
15 22
16 Roundup support code 23 Roundup support code
17 Installed into your Python install's lib directory 24 Installed into your Python install's lib directory
18 25
19 Roundup scripts 26 Roundup scripts
20 These include the email gateway, the roundup 27 These include the email gateway, the roundup
21 HTTP server, the roundup administration command-line interface, etc. 28 HTTP server, the roundup administration command-line interface, etc.
22 29
23 Roundup trackers 30
24 Trackers consist of core support files, issues 31 Prerequisites
25 (be they bug reports or otherwise), tracker configuration file(s), 32 =============
26 etc. Roundup trackers also adhere to a specific "Template" which 33
27 defines the fields usable/assignable on a per-issue basis. A 34 Python 2.1.1 or newer with a functioning anydbm or bsddb module. Download the
28 description of the provided templates follows. 35 latest version from http://www.python.org/. It is highly recommended that
36 users install the latest patch version of python - 2.1.3 or 2.2.1 - as these
37 contain many fixes to serious bugs.
38
39 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
40 later. Download the latest version from http://pybsddb.sourceforge.net/.
41
42
43 Getting Roundup
44 ===============
45
46 Download the latest version from http://roundup.sf.net/.
47
48 Testing your Python
49 -------------------
50
51 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
52 source directory and make sure there are no errors.
53 If there are errors, please let us know!
54
55 If the above fails, you may be using the wrong version of python. Try
56 ``python2 ./run_tests``. If that works, you will need to substitute
57 ``python2`` for ``python`` in all further commands you use in relation to
58 Roundup -- from installation and scripts.
59
60
61 Installation
62 ============
63
64 Set aside 15-30 minutes. Please make sure you're using a supported version of
65 Python -- see `testing your python`_. There's three sections to this
66 installation guide:
67
68 1. `basic installation steps`_ that all installers must follow
69 2. `shared environment steps`_ to take if you're installing on a shared
70 UNIX machine and want to restrict local access to roundup
71 3. `internet setup`_ steps to take if your tracker is to be used by the wider
72 internet community
73
74 Most users will only need to follow the first step, since the environment will
75 be a trusted one.
76
77
78 Basic Installation Steps
79 ------------------------
80
81 1. To install the Roundup support code into your Python tree and
82 Roundup scripts into /usr/local/bin::
83
84 python setup.py install
85
86 If you would like to place the Roundup scripts in a directory other
87 than ``/usr/local/bin``, then specify the preferred location with
88 ``--install-script``. For example, to install them in
89 ``/opt/roundup/bin``::
90
91 python setup.py install --install-scripts=/opt/roundup/bin
92
93 2. To create a Roundup tracker (necessary to do before you can
94 use the software in any real fashion):
95
96 a. (Optional) If you intend to keep your roundup trackers
97 under one top level directory which does not exist yet,
98 you should create that directory now. Example:
99
100 mkdir /opt/roundup/trackers
101
102 b. Either add the Roundup script location to your ``PATH``
103 environment variable or specify the full path to
104 the command in the next step.
105
106 c. ``roundup-admin install``
107
108 You will be asked a series of questions. Descriptions of the provided
109 templates can be found in `choosing your template`_ below. Descriptions
110 of the available backends can be found in `choosing your backend`_
111 below. The questions will be something like (you may have more
112 templates or backends available):
113
114 Enter tracker home: /opt/roundup/trackers/support
115 Templates: classic
116 Select template [classic]: classic
117 Back ends: anydbm, bsddb
118 Select backend [anydbm]: anydbm
119
120 You will now be directed to edit the tracker configuration and
121 initial schema. See `Customising Roundup`_ for details on configuration
122 and schema changes. Note that you may change any of the configuration
123 after you've initialised the tracker - it's just better to have valid
124 values for this stuff now.
125
126 d. ``roundup-admin initialise``
127
128 This step initialises the tracker database. You will need to supply
129 an admin password at this step. You will be prompted::
130
131 Admin Password:
132 Confirm:
133
134 Once this is done, the tracker has been created.
135
136 3. XXX Set up the CGI interface
137
138 4. XXX Set up the mail gateway
139
140
141 Choosing Your Template
142 ----------------------
29 143
30 Classic Template 144 Classic Template
31 ---------------- 145 ~~~~~~~~~~~~~~~~
32 146
33 The classic template is the one defined in the `Roundup Specification`_. It 147 The classic template is the one defined in the `Roundup Specification`_. It
34 holds issues which have priorities and statuses. Each issue may also have a 148 holds issues which have priorities and statuses. Each issue may also have a
35 set of messages which are disseminated to the issue's list of nosy users. 149 set of messages which are disseminated to the issue's list of nosy users.
36 150
37 151
38 Backends 152 Choosing Your Backend
39 -------- 153 ---------------------
40 154
41 The actual storage of Roundup tracker information is handled by backends. 155 The actual storage of Roundup tracker information is handled by backends.
42 There's several to choose from, each with benefits and limitations: 156 There's several to choose from, each with benefits and limitations:
43 157
44 **anydbm** 158 **anydbm**
55 This allows it to gain some performance and scaling benefits. 169 This allows it to gain some performance and scaling benefits.
56 **sqlite** 170 **sqlite**
57 This uses the SQLite embedded RDBMS to provide a fast, scaleable backend. 171 This uses the SQLite embedded RDBMS to provide a fast, scaleable backend.
58 There are no limitations, and it's much faster and more scaleable than the 172 There are no limitations, and it's much faster and more scaleable than the
59 dbm backends. 173 dbm backends.
174 **metakit**
175 This backend is implemented over the metakit storage system, using Mk4Py as
176 the interface. It scales much better than the dbm backends.
60 **gadfly** 177 **gadfly**
61 This is a proof-of-concept relational database backend, not really intended 178 This is a proof-of-concept relational database backend, not really intended
62 for actual production use, although it can be. It uses the Gadfly RDBMS 179 for actual production use, although it can be. It uses the Gadfly RDBMS
63 to store data. It is unable to perform string searches due to gadfly not 180 to store data. It is unable to perform string searches due to gadfly not
64 having a LIKE operation. It should scale well, assuming a client/server 181 having a LIKE operation. It should scale well, assuming a client/server
65 setup is used. 182 setup is used. It's much slower than even the dbm backends.
66 **metakit**
67 This backend is implemented over the metakit storage system, using Mk4Py as
68 the interface. It scales much better than the dbm backends, but has some
69 missing features:
70
71 - you may not unset properties once they are set
72 - journal retrieval is not implemented
73
74 183
75 Note: you may set your tracker up with the anydbm backend (which is guaranteed 184 Note: you may set your tracker up with the anydbm backend (which is guaranteed
76 to be available) and switch to one of the other backends at any time using the 185 to be available) and switch to one of the other backends at any time using the
77 instructions in the `maintenance documentation`_. 186 instructions in the `maintenance documentation`_.
78
79 Prerequisites
80 =============
81
82 Python 2.1.1 or newer with a functioning anydbm or bsddb module. Download the
83 latest version from http://www.python.org/. It is highly recommended that
84 users install the latest patch version of python - 2.1.3 or 2.2.1 - as these
85 contain many fixes to serious bugs.
86
87 If you want to use Berkeley DB bsddb3 with Roundup, use version 3.3.0 or
88 later. Download the latest version from http://pybsddb.sourceforge.net/.
89
90
91 Getting Roundup
92 ===============
93
94 Download the latest version from http://roundup.sf.net/.
95
96 Testing your Python
97 -------------------
98
99 Once you've unpacked roundup's source, run ``python ./run_tests`` in the
100 source directory and make sure there are no errors.
101 If there are errors, please let us know!
102
103 If the above fails, you may be using the wrong version of python. Try
104 ``python2 ./run_tests``. If that works, you will need to substitute
105 ``python2`` for ``python`` in all further commands you use in relation to
106 Roundup -- from installation and scripts.
107
108
109 Installation
110 ============
111
112 Set aside 15-30 minutes. Please make sure you're using a supported version of
113 Python -- see `testing your python`_. There's three sections to this
114 installation guide:
115
116 1. `basic installation steps`_ that all installers must follow
117 2. `shared environment steps`_ to take if you're installing on a shared
118 UNIX machine and want to restrict local access to roundup
119 3. `internet setup`_ steps to take if your tracker is to be used by the wider
120 internet community
121
122 Most users will only need to follow the first step, since the environment will
123 be a trusted one.
124
125
126 Basic Installation Steps
127 ------------------------
128
129 1. To install the Roundup support code into your Python tree and
130 Roundup scripts into /usr/local/bin::
131
132 python setup.py install
133
134 If you would like to place the Roundup scripts in a directory other
135 than ``/usr/local/bin``, then specify the preferred location with
136 ``--install-script``. For example, to install them in
137 ``/opt/roundup/bin``::
138
139 python setup.py install --install-scripts=/opt/roundup/bin
140
141 2. To create a Roundup tracker (necessary to do before you can
142 use the software in any real fashion):
143
144 a. (Optional) If you intend to keep your roundup trackers
145 under one top level directory which does not exist yet,
146 you should create that directory now. Example:
147
148 mkdir /opt/roundup/trackers
149
150 b. Either add the Roundup script location to your ``PATH``
151 environment variable or specify the full path to
152 the command in the next step.
153
154 c. ``roundup-admin install``
155
156 You will be asked a series of questions. A description of
157 the Roundup-provided templates can be found under the Overview_::
158
159 Enter tracker home: /opt/roundup/trackers/support
160 Templates: classic, extended
161 Select template [classic]: classic
162 Back ends: anydbm, bsddb
163 Select backend [anydbm]: anydbm
164
165 You will now be directed to edit the tracker configuration and
166 initial schema. See `Customising Roundup`_ for details on configuration
167 and schema changes. Note that you may change any of the configuration
168 after you've initialised the tracker - it's just better to have valid
169 values for this stuff now.
170
171 d. ``roundup-admin initialise``
172
173 This step initialises the tracker database. You will need to supply
174 an admin password at this step. You will be prompted::
175
176 Admin Password:
177 Confirm:
178
179 Once this is done, the tracker has been created.
180
181 3. XXX Set up the CGI interface
182
183 4. XXX Set up the mail gateway
184 187
185 188
186 Shared Environment Steps 189 Shared Environment Steps
187 ------------------------ 190 ------------------------
188 191
Roundup Issue Tracker: http://roundup-tracker.org/