Mercurial > p > roundup > code
comparison doc/admin_guide.txt @ 2003:a291bf753037
maintenance -> admin guide
| author | Richard Jones <richard@users.sourceforge.net> |
|---|---|
| date | Wed, 11 Feb 2004 00:41:33 +0000 |
| parents | |
| children | fc52d57c6c3e |
comparison
equal
deleted
inserted
replaced
| 2002:b046b65e51db | 2003:a291bf753037 |
|---|---|
| 1 ==================== | |
| 2 Administration Guide | |
| 3 ==================== | |
| 4 | |
| 5 :Version: $Revision: 1.1 $ | |
| 6 | |
| 7 .. contents:: | |
| 8 | |
| 9 What does Roundup install? | |
| 10 ========================== | |
| 11 | |
| 12 There's two "installations" that we talk about when using Roundup: | |
| 13 | |
| 14 1. The installation of the software and its support files. This uses the | |
| 15 standard Python mechanism called "distutils" and thus Roundup's core code, | |
| 16 executable scripts and support data files are installed in Python's | |
| 17 directories. On Windows, this is typically: | |
| 18 | |
| 19 Scripts | |
| 20 <python dir>\scripts\... | |
| 21 Core code | |
| 22 <python dir>\lib\site-packages\roundup\... | |
| 23 Support files | |
| 24 <python dir>\share\roundup\... | |
| 25 | |
| 26 and on *nix (eg. Linux): | |
| 27 | |
| 28 Scripts | |
| 29 <python root>/bin/... | |
| 30 Core code | |
| 31 <python root>/lib-<python version>/site-packages/roundup/... | |
| 32 Support files | |
| 33 <python root>/share/roundup/... | |
| 34 | |
| 35 2. The installation of a specific tracker. When invoking the roundup-admin | |
| 36 "inst" (and "init") commands, you're creating a new Roundup tracker. This | |
| 37 installs configuration files, HTML templates, detector code and a new | |
| 38 database. You have complete control over where this stuff goes through | |
| 39 both choosing your "tracker home" and the DATABASE variable in | |
| 40 config.py. | |
| 41 | |
| 42 | |
| 43 Users and Security | |
| 44 ================== | |
| 45 | |
| 46 Roundup holds its own user database which primarily contains a username, | |
| 47 password and email address for the user. Roundup *must* have its own user | |
| 48 listing, in order to maintain internal consistency of its data. It is a | |
| 49 relatively simple exercise to update this listing on a regular basis, or on | |
| 50 demand, so that it matches an external listing (eg. unix passwd file, LDAP, | |
| 51 etc.) | |
| 52 | |
| 53 Roundup identifies users in a number of ways: | |
| 54 | |
| 55 1. Through the web, users may be identified by either HTTP Basic | |
| 56 Authentication or cookie authentication. If you are running the web | |
| 57 server (roundup-server) through another HTTP server (eg. apache or IIS) | |
| 58 then that server may require HTTP Basic Authentication, and it will pass | |
| 59 the ``REMOTE_USER`` variable through to Roundup. If this variable is not | |
| 60 present, then Roundup defaults to using its own cookie-based login | |
| 61 mechanism. | |
| 62 2. In email messages handled by roundup-mailgw, users are identified by the | |
| 63 From address in the message. | |
| 64 | |
| 65 In both cases, Roundup's behaviour when dealing with unknown users is | |
| 66 controlled by Permissions defined in the "SECURITY SETTINGS" section of the | |
| 67 tracker's ``dbinit.py`` module: | |
| 68 | |
| 69 Web Registration | |
| 70 If granted to the Anonymous Role, then anonymous users will be able to | |
| 71 register through the web. | |
| 72 Email Registration | |
| 73 If granted to the Anonymous Role, then email messages from unknown users | |
| 74 will result in those users being registered with the tracker. | |
| 75 | |
| 76 More information about how to customise your tracker's security settings | |
| 77 may be found in the `customisation documentation`_. | |
| 78 | |
| 79 Tasks | |
| 80 ===== | |
| 81 | |
| 82 Maintenance of Roundup can involve one of the following: | |
| 83 | |
| 84 1. `tracker backup`_ | |
| 85 2. `software upgrade`_ | |
| 86 3. `migrating backends`_ | |
| 87 3. `moving a tracker`_ | |
| 88 | |
| 89 | |
| 90 Tracker Backup | |
| 91 -------------- | |
| 92 | |
| 93 Stop the web and email frontends and to copy the contents of the tracker home | |
| 94 directory to some other place using standard backup tools. | |
| 95 | |
| 96 | |
| 97 Software Upgrade | |
| 98 ---------------- | |
| 99 | |
| 100 Always make a backup of your tracker before upgrading software. Steps you may | |
| 101 take: | |
| 102 | |
| 103 1. ensure that the unit tests run on your system | |
| 104 2. copy your tracker home to a new directory | |
| 105 3. follow the steps in the upgrading documentation for the new version of | |
| 106 the software | |
| 107 4. test each of the admin tool, web interface and mail gateway using the new | |
| 108 version of the software | |
| 109 5. stop the production web and email frontends | |
| 110 6. perform the upgrade steps on the existing tracker directory | |
| 111 7. upgrade the software | |
| 112 8. restart your tracker | |
| 113 | |
| 114 | |
| 115 Migrating Backends | |
| 116 ------------------ | |
| 117 | |
| 118 1. stop the existing tracker web and email frontends (preventing changes) | |
| 119 2. use the roundup-admin tool "export" command to export the contents of | |
| 120 your tracker to disk | |
| 121 3. copy the tracker home to a new directory | |
| 122 4. change the backend used in the tracker home ``select_db.py`` file | |
| 123 5. delete the "db" directory from the new directory | |
| 124 6. use the roundup-admin "import" command to import the previous export with | |
| 125 the new tracker home | |
| 126 7. test each of the admin tool, web interface and mail gateway using the new | |
| 127 backend | |
| 128 8. move the old tracker home out of the way (rename to "tracker.old") and | |
| 129 move the new tracker home into its place | |
| 130 9. restart web and email frontends | |
| 131 | |
| 132 | |
| 133 Moving a Tracker | |
| 134 ---------------- | |
| 135 | |
| 136 If you're moving the tracker to a similar machine, you should: | |
| 137 | |
| 138 1. install Roundup on the new machine and test that it works there, | |
| 139 2. stop the existing tracker web and email frontends (preventing changes), | |
| 140 3. copy the tracker home directory over to the new machine, and | |
| 141 4. start the tracker web and email frontends on the new machine. | |
| 142 | |
| 143 Most of the backends are actually portable across platforms (ie. from Unix to | |
| 144 Windows to Mac). If this isn't the case (ie. the tracker doesn't work when | |
| 145 moved using the above steps) then you'll need to: | |
| 146 | |
| 147 1. install Roundup on the new machine and test that it works there, | |
| 148 2. stop the existing tracker web and email frontends (preventing changes), | |
| 149 3. use the roundup-admin tool "export" command to export the contents of | |
| 150 the existing tracker, | |
| 151 4. copy the export to the new machine, | |
| 152 5. use the roundup-admin "import" command to import the tracker on the new | |
| 153 machine, and | |
| 154 6. start the tracker web and email frontends on the new machine. | |
| 155 | |
| 156 | |
| 157 ------------------- | |
| 158 | |
| 159 Back to `Table of Contents`_ | |
| 160 | |
| 161 .. _`Table of Contents`: index.html | |
| 162 .. _`customisation documentation`: customizing.html | |
| 163 |