Mercurial > p > roundup > code

annotate doc/admin_guide.txt @ 4305:e39b88a7150a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
- update with possible tracker issue
author Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
date Mon, 14 Dec 2009 21:48:51 +0000
parents be9122d753c5
children 47bd330e3d17
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 ====================
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 Administration Guide
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 ====================
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 .. contents::
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 What does Roundup install?
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8 ==========================
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 There's two "installations" that we talk about when using Roundup:
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 1. The installation of the software and its support files. This uses the
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 standard Python mechanism called "distutils" and thus Roundup's core code,
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 executable scripts and support data files are installed in Python's
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 directories. On Windows, this is typically:
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 Scripts
2068
65b5297b488f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2005
diff changeset
18 ``<python dir>\scripts\...``
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 Core code
2068
65b5297b488f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2005
diff changeset
20 ``<python dir>\lib\site-packages\roundup\...``
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 Support files
2068
65b5297b488f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2005
diff changeset
22 ``<python dir>\share\roundup\...``
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23
2005
fc52d57c6c3e documentation cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
24 and on Unix-like systems (eg. Linux):
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 Scripts
2068
65b5297b488f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2005
diff changeset
27 ``<python root>/bin/...``
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28 Core code
2068
65b5297b488f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2005
diff changeset
29 ``<python root>/lib-<python version>/site-packages/roundup/...``
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30 Support files
2068
65b5297b488f *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2005
diff changeset
31 ``<python root>/share/roundup/...``
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 2. The installation of a specific tracker. When invoking the roundup-admin
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 "inst" (and "init") commands, you're creating a new Roundup tracker. This
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35 installs configuration files, HTML templates, detector code and a new
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36 database. You have complete control over where this stuff goes through
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
37 both choosing your "tracker home" and the ``main`` -> ``database`` variable
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
38 in the tracker's config.ini.
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
41 Configuring Roundup's Logging of Messages For Sysadmins
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
42 =======================================================
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
43
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
44 You may configure where Roundup logs messages in your tracker's config.ini
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
45 file. Roundup will use the standard Python (2.3+) logging implementation
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
46 when available. If not, then a very basic logging implementation will be used
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
47 (see BasicLogging in the roundup.rlog module for details).
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
48
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
49 Configuration for standard "logging" module:
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
50 - tracker configuration file specifies the location of a logging
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
51 configration file as ``logging`` -> ``config``
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
52 - ``roundup-server`` specifies the location of a logging configuration
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
53 file on the command line
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
54 Configuration for "BasicLogging" implementation:
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
55 - tracker configuration file specifies the location of a log file
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
56 ``logging`` -> ``filename``
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
57 - tracker configuration file specifies the level to log to as
2921
ad4fb8a14a97 more doc updates, not so many TODOs any more
Richard Jones <richard@users.sourceforge.net>
parents: 2632
diff changeset
58 ``logging`` -> ``level``
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
59 - ``roundup-server`` specifies the location of a log file on the command
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
60 line
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
61 - ``roundup-server`` specifies the level to log to on the command line
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
62
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
63 (``roundup-mailgw`` always logs to the tracker's log file)
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
64
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
65 In both cases, if no logfile is specified then logging will simply be sent
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
66 to sys.stderr with only logging of ERROR messages.
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
67
3250
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
68
2632
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
69 Configuring roundup-server
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
70 ==========================
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
71
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
72 The basic configuration file layout is as follows (take from the
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
73 ``roundup-server.ini.example`` file in the "doc" directory)::
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
74
3465
81542d49c8cb fix admin doc description of roundup-server config file
Richard Jones <richard@users.sourceforge.net>
parents: 3341
diff changeset
75 [main]
2632
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
76 port = 8080
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
77 ;hostname =
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
78 ;user =
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
79 ;group =
2632
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
80 ;log_ip = yes
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
81 ;pidfile =
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
82 ;logfile =
3880
2359d6304a4f Allow template for tracker index page
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3781
diff changeset
83 ;template =
3883
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
84 ;ssl = no
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
85 ;pem =
2632
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
86
3465
81542d49c8cb fix admin doc description of roundup-server config file
Richard Jones <richard@users.sourceforge.net>
parents: 3341
diff changeset
87 [trackers]
2632
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
88 ; Add one of these per tracker being served
3465
81542d49c8cb fix admin doc description of roundup-server config file
Richard Jones <richard@users.sourceforge.net>
parents: 3341
diff changeset
89 name = /path/to/tracker/name
2632
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
90
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
91 Values ";commented out" are optional. The meaning of the various options
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
92 are as follows:
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
93
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
94 **port**
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
95 Defines the local TCP port to listen for clients on.
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
96 **hostname**
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
97 Defines the local hostname to listen for clients on. Only required if
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
98 "localhost" is not sufficient.
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
99 **user** and **group**
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
100 Defines the Unix user and group to run the server as. Only work if the
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
101 server is started as root.
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
102 **log_ip**
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
103 If ``yes`` then we log IP addresses against accesses. If ``no`` then we
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
104 log the hostname of the client. The latter can be much slower.
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
105 **pidfile**
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
106 If specified, the server will fork at startup and write its new PID to
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
107 the file.
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
108 **logfile**
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
109 Any unhandled exception messages or other output from Roundup will be
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
110 written to this file. It must be specified if **pidfile** is specified.
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
111 If per-tracker logging is specified, then very little will be written to
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
112 this file.
3880
2359d6304a4f Allow template for tracker index page
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3781
diff changeset
113 **template**
2359d6304a4f Allow template for tracker index page
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3781
diff changeset
114 Specifies a template used for displaying the tracker index when
2359d6304a4f Allow template for tracker index page
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3781
diff changeset
115 multiple trackers are being used. The variable "trackers" is available
2359d6304a4f Allow template for tracker index page
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3781
diff changeset
116 to the template and is a dict of all configured trackers.
3883
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
117 **ssl**
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
118 Enables the use of SSL to secure the connection to the roundup-server.
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
119 If you enable this, ensure that your tracker's config.ini specifies
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
120 an *https* URL.
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
121 **pem**
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
122 If specified, the SSL PEM file containing the private key and certificate.
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
123 If not specified, roundup will generate a temporary, self-signed certificate
679118b572d5 add SSL to roundup-server via pyopenssl
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3880
diff changeset
124 for use.
3465
81542d49c8cb fix admin doc description of roundup-server config file
Richard Jones <richard@users.sourceforge.net>
parents: 3341
diff changeset
125 **trackers** section
81542d49c8cb fix admin doc description of roundup-server config file
Richard Jones <richard@users.sourceforge.net>
parents: 3341
diff changeset
126 Each line denotes a mapping from a URL component to a tracker home.
81542d49c8cb fix admin doc description of roundup-server config file
Richard Jones <richard@users.sourceforge.net>
parents: 3341
diff changeset
127 Make sure the name part doesn't include any url-unsafe characters like
81542d49c8cb fix admin doc description of roundup-server config file
Richard Jones <richard@users.sourceforge.net>
parents: 3341
diff changeset
128 spaces. Stick to alphanumeric characters and you'll be ok.
2632
9c55f2bc5961 roundup-server now has a configuration file (-C option)
Richard Jones <richard@users.sourceforge.net>
parents: 2572
diff changeset
129
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
130
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 Users and Security
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 ==================
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 Roundup holds its own user database which primarily contains a username,
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135 password and email address for the user. Roundup *must* have its own user
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 listing, in order to maintain internal consistency of its data. It is a
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 relatively simple exercise to update this listing on a regular basis, or on
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 demand, so that it matches an external listing (eg. unix passwd file, LDAP,
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139 etc.)
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 Roundup identifies users in a number of ways:
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 1. Through the web, users may be identified by either HTTP Basic
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144 Authentication or cookie authentication. If you are running the web
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 server (roundup-server) through another HTTP server (eg. apache or IIS)
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 then that server may require HTTP Basic Authentication, and it will pass
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147 the ``REMOTE_USER`` variable through to Roundup. If this variable is not
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 present, then Roundup defaults to using its own cookie-based login
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 mechanism.
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 2. In email messages handled by roundup-mailgw, users are identified by the
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 From address in the message.
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153 In both cases, Roundup's behaviour when dealing with unknown users is
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 controlled by Permissions defined in the "SECURITY SETTINGS" section of the
2983
9614a101b68f Stuff from the train ride this morning:
Richard Jones <richard@users.sourceforge.net>
parents: 2921
diff changeset
155 tracker's ``schema.py`` module:
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157 Web Registration
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 If granted to the Anonymous Role, then anonymous users will be able to
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159 register through the web.
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 Email Registration
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 If granted to the Anonymous Role, then email messages from unknown users
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162 will result in those users being registered with the tracker.
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 More information about how to customise your tracker's security settings
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165 may be found in the `customisation documentation`_.
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166
2572
d15b71b8a85a more logging goodness
Richard Jones <richard@users.sourceforge.net>
parents: 2479
diff changeset
167
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 Tasks
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 =====
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171 Maintenance of Roundup can involve one of the following:
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
173 1. `tracker backup`_
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 2. `software upgrade`_
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 3. `migrating backends`_
2005
fc52d57c6c3e documentation cleanup
Richard Jones <richard@users.sourceforge.net>
parents: 2003
diff changeset
176 4. `moving a tracker`_
3250
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
177 5. `migrating from other software`_
3341
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
178 6. `adding a user from the command-line`_
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 Tracker Backup
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 --------------
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183
3959
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
184 The roundup-admin import and export commands are **not** recommended for
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
185 performing backup.
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
186
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
187 Optionally stop the web and email frontends and to copy the contents of the
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
188 tracker home directory to some other place using standard backup tools.
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
189 This means using
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
190 *pg_dump* to take a snapshot of your Postgres backend database, for example.
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
191 A simple copy of the tracker home (and files storage area if you've configured
f764931f2c67 more words about backing up
Richard Jones <richard@users.sourceforge.net>
parents: 3883
diff changeset
192 it to be elsewhere) will then complete the backup.
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195 Software Upgrade
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196 ----------------
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198 Always make a backup of your tracker before upgrading software. Steps you may
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 take:
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200
2478
3ab2b91cdd2c *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2474
diff changeset
201 1. Ensure that the unit tests run on your system::
2474
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
202
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
203 python run_tests.py
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
204
2387
4962f99aaa27 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2203
diff changeset
205 2. If you're using an RDBMS backend, make a backup of its contents now.
2478
3ab2b91cdd2c *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2474
diff changeset
206 3. Make a backup of the tracker home itself.
3ab2b91cdd2c *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2474
diff changeset
207 4. Stop the tracker web and email frontends.
4014
b80224c1f4e3 fix poor docs
Richard Jones <richard@users.sourceforge.net>
parents: 3963
diff changeset
208 5. Install the new version of the software::
b80224c1f4e3 fix poor docs
Richard Jones <richard@users.sourceforge.net>
parents: 3963
diff changeset
209
b80224c1f4e3 fix poor docs
Richard Jones <richard@users.sourceforge.net>
parents: 3963
diff changeset
210 python setup.py install
b80224c1f4e3 fix poor docs
Richard Jones <richard@users.sourceforge.net>
parents: 3963
diff changeset
211
b80224c1f4e3 fix poor docs
Richard Jones <richard@users.sourceforge.net>
parents: 3963
diff changeset
212 6. Follow the steps in the `upgrading documentation`_ for the new version of
2387
4962f99aaa27 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2203
diff changeset
213 the software in the copied.
3963
3230f9c88086 Fix race condition for key properties in rdbms backends [SF#1876683]
Richard Jones <richard@users.sourceforge.net>
parents: 3959
diff changeset
214
3230f9c88086 Fix race condition for key properties in rdbms backends [SF#1876683]
Richard Jones <richard@users.sourceforge.net>
parents: 3959
diff changeset
215 Usually you will be asked to run `roundup_admin migrate` on your tracker
3230f9c88086 Fix race condition for key properties in rdbms backends [SF#1876683]
Richard Jones <richard@users.sourceforge.net>
parents: 3959
diff changeset
216 before you allow users to start accessing the tracker.
3230f9c88086 Fix race condition for key properties in rdbms backends [SF#1876683]
Richard Jones <richard@users.sourceforge.net>
parents: 3959
diff changeset
217
3230f9c88086 Fix race condition for key properties in rdbms backends [SF#1876683]
Richard Jones <richard@users.sourceforge.net>
parents: 3959
diff changeset
218 It's safe to run this even if it's not required, so just get into the
3230f9c88086 Fix race condition for key properties in rdbms backends [SF#1876683]
Richard Jones <richard@users.sourceforge.net>
parents: 3959
diff changeset
219 habit.
4014
b80224c1f4e3 fix poor docs
Richard Jones <richard@users.sourceforge.net>
parents: 3963
diff changeset
220 7. Restart your tracker web and email frontends.
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221
2474
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
222 If something bad happens, you may reinstate your backup of the tracker and
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
223 reinstall the older version of the sofware using the same install command::
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
224
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
225 python setup.py install
591e3cfe622a more detail
Richard Jones <richard@users.sourceforge.net>
parents: 2405
diff changeset
226
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 Migrating Backends
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229 ------------------
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230
3781
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
231 1. Stop the existing tracker web and email frontends (preventing changes).
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
232 2. Use the roundup-admin tool "export" command to export the contents of
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
233 your tracker to disk.
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
234 3. Copy the tracker home to a new directory.
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
235 4. Delete the "db" directory from the new directory.
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
236 5. Enter the new backend name in the tracker home ``db/backend_name`` file.
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
237 6. Use the roundup-admin "import" command to import the previous export with
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
238 the new tracker home. If non-interactively::
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
239
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
240 roundup-admin -i <tracker home> import <tracker export dir>
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
241
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
242 If interactively, enter 'commit' before exitting.
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
243 7. Test each of the admin tool, web interface and mail gateway using the new
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
244 backend.
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
245 8. Move the old tracker home out of the way (rename to "tracker.old") and
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
246 move the new tracker home into its place.
e03014a96a95 doc improvement
Richard Jones <richard@users.sourceforge.net>
parents: 3780
diff changeset
247 9. Restart web and email frontends.
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250 Moving a Tracker
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251 ----------------
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253 If you're moving the tracker to a similar machine, you should:
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
254
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255 1. install Roundup on the new machine and test that it works there,
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 2. stop the existing tracker web and email frontends (preventing changes),
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 3. copy the tracker home directory over to the new machine, and
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258 4. start the tracker web and email frontends on the new machine.
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260 Most of the backends are actually portable across platforms (ie. from Unix to
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262 moved using the above steps) then you'll need to:
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264 1. install Roundup on the new machine and test that it works there,
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265 2. stop the existing tracker web and email frontends (preventing changes),
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266 3. use the roundup-admin tool "export" command to export the contents of
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 the existing tracker,
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 4. copy the export to the new machine,
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269 5. use the roundup-admin "import" command to import the tracker on the new
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270 machine, and
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271 6. start the tracker web and email frontends on the new machine.
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273
3250
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
274 Migrating From Other Software
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
275 -----------------------------
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
276
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
277 You have a couple of choices. You can either use a CSV import into Roundup,
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
278 or you can write a simple Python script which uses the Roundup API
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
279 directly. The latter is almost always simpler -- see the "scripts"
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
280 directory in the Roundup source for some example uses of the API.
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
281
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
282 "roundup-admin import" will import data into your tracker from a
3250
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
283 directory containing files with the following format:
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
284
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
285 - one colon-separated-values file per Class with columns for each property,
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
286 named <classname>.csv
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
287 - one colon-separated-values file per Class with journal information,
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
288 named <classname>-journals.csv (this is required, even if it's empty)
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
289 - if the Class is a FileClass, you may have the "content" property
3250
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
290 stored in separate files from the csv files. This goes in a directory
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
291 structure::
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
292
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
293 <classname>-files/<N>/<designator>
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
294
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
295 where ``<designator>`` is the item's ``<classname><id>`` combination.
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
296 The ``<N>`` value is ``int(<id> / 1000)``.
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
297
8634ea9b2d1c doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 3089
diff changeset
298
3341
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
299 Adding A User From The Command-Line
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
300 -----------------------------------
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
301
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
302 The ``roundup-admin`` program can create any data you wish to in the
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
303 database. To create a new user, use::
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
304
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
305 roundup-admin create user
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
306
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
307 To figure out what good values might be for some of the fields (eg. Roles)
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
308 you can just display another user::
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
309
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
310 roundup-admin list user
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
311
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
312 (or if you know their username, and it happens to be "richard")::
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
313
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
314 roundup-admin find username=richard
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
315
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
316 then using the user id you get from one of the above commands, you may
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
317 display the user's details::
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
318
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
319 roundup-admin display <userid>
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
320
df693c0aaba9 more admin guide goodness
Richard Jones <richard@users.sourceforge.net>
parents: 3282
diff changeset
321
2177
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
322 Running the Servers
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
323 ===================
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
324
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
325 Unix
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
326 ----
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
327
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
328 On Unix systems, use the scripts/server-ctl script to control the
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
329 roundup-server server. Copy it somewhere and edit the variables at the top
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
330 to reflect your specific installation.
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
331
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
332
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
333 Windows
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
334 -------
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
335
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
336 On Windows, the roundup-server program runs as a Windows Service, and
2405
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
337 therefore may be controlled through the Services control panel. The
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
338 roundup-server program may also control the service directly:
2177
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
339
2405
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
340 **install the service**
3779
ee73abcc95d2 Sorry, another mega-patch:
Richard Jones <richard@users.sourceforge.net>
parents: 3465
diff changeset
341 ``roundup-server -C /path/to/my/roundup-server.ini -c install``
2405
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
342 **start the service**
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
343 ``roundup-server -c start``
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
344 **stop the service**
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
345 ``roundup-server -c stop``
2177
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
346
2405
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
347 To bring up the services panel:
2177
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
348
2405
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
349 Windows 2000 and later
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
350 Start/Control Panel/Administrative Tools/Services
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
351 Windows NT4
1736886eefb3 more windows info
Richard Jones <richard@users.sourceforge.net>
parents: 2387
diff changeset
352 Start/Control Panel/Services
2177
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
353
3780
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
354 You will need a server configuration file (as described in
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
355 `Configuring roundup-server`_) for specifying tracker homes
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
356 and other roundup-server configuration. Specify the name of
158e31bbf86a recent patch had lines longer than 80 chars - rewrap; trim trailing spaces
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 3779
diff changeset
357 this file using the ``-C`` switch when installing the service.
3779
ee73abcc95d2 Sorry, another mega-patch:
Richard Jones <richard@users.sourceforge.net>
parents: 3465
diff changeset
358
2203
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
359 Running the Mail Gateway Script
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
361
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
362 The mail gateway script should be scheduled to run regularly on your
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
363 Windows server. Normally this will result in a window popping up. The
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
364 solution to this is to:
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
365
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
366 1. Create a new local account on the Roundup server
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
367 2. Set the scheduled task to run in the context of this user instead
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
368 of your normal login
4a157c198585 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2177
diff changeset
369
2177
a276e2531321 info about running roundup-server... more needed :)
Richard Jones <richard@users.sourceforge.net>
parents: 2068
diff changeset
370
2003
a291bf753037 maintenance -> admin guide
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
371 .. _`customisation documentation`: customizing.html
2387
4962f99aaa27 *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents: 2203
diff changeset
372 .. _`upgrading documentation`: upgrading.html
Roundup Issue Tracker: http://roundup-tracker.org/