Mercurial > p > roundup > code
comparison doc/installation.txt @ 659:e429649ed124
More documentation cleanups.
- renamed .stx to .txt so they're identifiable as readable files.
- fixed FAQ and announcement formatting
| author | Richard Jones <richard@users.sourceforge.net> |
|---|---|
| date | Wed, 13 Mar 2002 23:00:48 +0000 |
| parents | |
| children | c52122f38c9b 54333751e98d |
comparison
equal
deleted
inserted
replaced
| 658:1409d4d55f92 | 659:e429649ed124 |
|---|---|
| 1 Installing Roundup | |
| 2 ================== | |
| 3 | |
| 4 `Table of contents`_ | |
| 5 | |
| 6 - Overview_ | |
| 7 | |
| 8 - `Classic Template`_ | |
| 9 - `Extended Template`_ | |
| 10 | |
| 11 - Prerequisites_ | |
| 12 | |
| 13 - `Testing your Python`_ | |
| 14 | |
| 15 - `Getting Roundup`_ | |
| 16 - `Installation`_ | |
| 17 - `Further Reading`_ | |
| 18 - `Platform-Specific Notes`_ | |
| 19 | |
| 20 Overview | |
| 21 ======== | |
| 22 | |
| 23 Broken out separately, there are several conceptual pieces to a | |
| 24 Roundup installation: | |
| 25 | |
| 26 Roundup support code | |
| 27 Installed into your Python install's lib directory | |
| 28 | |
| 29 Roundup scripts | |
| 30 These include the email gateway, the roundup | |
| 31 HTTP server, the roundup administration command-line interface, etc. | |
| 32 | |
| 33 Roundup instances | |
| 34 Instances consist of core support files, issues | |
| 35 (be they bug reports or otherwise), instance configuration file(s), | |
| 36 etc. Roundup instances also adhere to a specific "Template" which | |
| 37 defines the fields usable/assignable on a per-issue basis. A | |
| 38 description of the provided templates follows. | |
| 39 | |
| 40 Classic Template | |
| 41 ---------------- | |
| 42 | |
| 43 The classic template is the one defined in the `Roundup Specification`_. It | |
| 44 holds issues which have priorities and statuses. Each issue may also have a | |
| 45 set of messages which are disseminated to the issue's list of nosy users. | |
| 46 | |
| 47 | |
| 48 Extended Template | |
| 49 ----------------- | |
| 50 | |
| 51 The extended template adds additional information to issues: product, | |
| 52 platform, version, targetversion and supportcall. | |
| 53 There is an additional class for | |
| 54 handling support calls, which includes a time log, customername, rate and | |
| 55 source. | |
| 56 | |
| 57 The priorty class has different default entries too: "fatal-bug", "bug", | |
| 58 "usability" and "feature". | |
| 59 | |
| 60 Users of this template will want to change the contents of the product | |
| 61 class as soon as the instance is created. | |
| 62 | |
| 63 | |
| 64 Prerequisites | |
| 65 ============= | |
| 66 | |
| 67 Python 2.1.1 or newer with a functioning anydbm or bsddb module. | |
| 68 | |
| 69 Download the latest version from http://www.python.org/. | |
| 70 | |
| 71 | |
| 72 Testing your Python | |
| 73 ------------------- | |
| 74 | |
| 75 Run ``"python -c 'import test;test.go()'"`` and make sure there | |
| 76 are no errors. If there are errors, please let us know! | |
| 77 | |
| 78 | |
| 79 Getting Roundup | |
| 80 =============== | |
| 81 | |
| 82 Download the latest version from http://roundup.sf.net/. | |
| 83 | |
| 84 | |
| 85 Installation | |
| 86 ============ | |
| 87 | |
| 88 Set aside 15-30 minutes. | |
| 89 | |
| 90 1. To install the Roundup support code into your Python tree and | |
| 91 Roundup scripts into /usr/local/bin:: | |
| 92 | |
| 93 python setup.py install | |
| 94 | |
| 95 If you would like to place the Roundup scripts in a directory other | |
| 96 than ``/usr/local/bin``, use the ``--install-scripts`` option as follows, | |
| 97 replacing ``/opt/roundup/bin`` with the location where you would like | |
| 98 the scripts to reside:: | |
| 99 | |
| 100 python setup.py install --install-scripts=/opt/roundup/bin | |
| 101 | |
| 102 2. To create a Roundup instance (necessary to do before you can | |
| 103 use the software in any real fashion): | |
| 104 | |
| 105 a. (Optional) If you intend to keep your roundup instances | |
| 106 under one top level directory which does not exist yet, | |
| 107 you should create that directory now. Example: | |
| 108 | |
| 109 mkdir /opt/roundup/instances | |
| 110 | |
| 111 b. Either add the Roundup script location to your ``PATH`` | |
| 112 environment variable or specify the full path to | |
| 113 the command in the next step. | |
| 114 | |
| 115 c. ``roundup-admin init`` | |
| 116 | |
| 117 You will be asked a series of questions. A description of | |
| 118 the Roundup-provided templates can be found under the Overview_:: | |
| 119 | |
| 120 Enter instance home: /opt/roundup/instances/support | |
| 121 Templates: classic, extended | |
| 122 Select template [classic]: classic | |
| 123 Back ends: anydbm, bsddb | |
| 124 Select backend [anydbm]: anydbm | |
| 125 Admin Password: | |
| 126 Confirm: | |
| 127 | |
| 128 3. Each instance ideally should have its own UNIX group, so create | |
| 129 a UNIX group (edit ``/etc/group`` or your appropriate NIS map if | |
| 130 you're using NIS). To continue with my examples so far, I would | |
| 131 create the UNIX group 'support', although the name of the UNIX | |
| 132 group does not have to be the same as the instance name. To this | |
| 133 'support' group I then add all of the UNIX usernames who will be | |
| 134 working with this Roundup instance. In addition to 'real' users, | |
| 135 the Roundup email gateway will need to have permissions to this | |
| 136 area as well, so add the user your mail service runs as to the | |
| 137 group. The UNIX group might then look like:: | |
| 138 | |
| 139 support:*:1002:jblaine,samh,geezer,mail | |
| 140 | |
| 141 If you intend to use the web interface (as most people do), you | |
| 142 should also add the username your web server runs as to the group. | |
| 143 My group now looks like this:: | |
| 144 | |
| 145 support:*:1002:jblaine,samh,geezer,mail,apache | |
| 146 | |
| 147 4. Configure your new instance by editing the file ``instance_config.py`` | |
| 148 located in the instance home you specified in step 2c above. This | |
| 149 file is Python code and must adhere to Python syntax rules, but | |
| 150 don't be daunted if you do not know Python - it should look pretty | |
| 151 straightfoward if you carefully read the comments in the file. | |
| 152 | |
| 153 5. There are two supported ways to get emailed issues into the | |
| 154 Roundup instance. You should pick ONE of the following, both | |
| 155 of which will continue my example setup from above: | |
| 156 | |
| 157 a. Set up a mail alias called "support" as:: | |
| 158 | |
| 159 "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support" | |
| 160 | |
| 161 If you use Sendmail's ``smrsh`` mechanism, please read the notes | |
| 162 under 'Platform-Specific Notes' | |
| 163 | |
| 164 b. OR... Configure roundup-mailgw to run every 10 minutes or | |
| 165 so via ``cron``. My cron job would be (these 2 lines all on one | |
| 166 line):: | |
| 167 | |
| 168 10 * * * * /opt/roundup/bin/roundup-mailgw | |
| 169 /opt/roundup/instances/support /var/mail/support | |
| 170 | |
| 171 6. TODO (mention perms) | |
| 172 | |
| 173 7. Test the email gateway. Under most flavors of UNIX, this | |
| 174 can be done by:: | |
| 175 | |
| 176 echo test | mail -s '[issue] test' support@YOUR_DOMAIN_HERE | |
| 177 | |
| 178 TODO (finish) | |
| 179 | |
| 180 | |
| 181 Further Reading | |
| 182 =============== | |
| 183 | |
| 184 If you intend to use Roundup with anything other than the defualt | |
| 185 templates, if you would like to hack on Roundup, or if you would | |
| 186 like implementation details, you should read `Customising Roundup`_. | |
| 187 | |
| 188 | |
| 189 Platform-Specific Notes | |
| 190 ======================= | |
| 191 | |
| 192 Sendmail smrsh | |
| 193 -------------- | |
| 194 | |
| 195 If you use Sendmail's ``smrsh`` mechanism, you will need to tell | |
| 196 smrsh that roundup-mailgw is a valid/trusted mail handler | |
| 197 before it will work. | |
| 198 | |
| 199 This is usually done via the following 2 steps: | |
| 200 | |
| 201 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw`` | |
| 202 which points to the full path of your actual ``roundup-mailgw`` | |
| 203 script. | |
| 204 | |
| 205 2. change your alias to ``"|roundup-mailgw <instance_home>"`` | |
| 206 | |
| 207 | |
| 208 Linux | |
| 209 ----- | |
| 210 | |
| 211 Python 2.1.1 as shipped with SuSE7.3 might be missing module | |
| 212 ``_weakref``. | |
| 213 | |
| 214 ------------------------------------------------------------------------------- | |
| 215 | |
| 216 Next: `Getting Started`_ | |
| 217 | |
| 218 .. _`table of contents`: index.html | |
| 219 .. _`getting started`: getting_started.html | |
| 220 .. _`roundup specification`: spec.html | |
| 221 .. _`customising roundup`: customizing.html | |
| 222 | |
| 223 $Id: installation.txt,v 1.1 2002-03-13 23:00:48 richard Exp $ |