==================== Administration Guide ==================== :Version: $Revision: 1.2 $ .. contents:: What does Roundup install? ========================== There's two "installations" that we talk about when using Roundup: 1. The installation of the software and its support files. This uses the standard Python mechanism called "distutils" and thus Roundup's core code, executable scripts and support data files are installed in Python's directories. On Windows, this is typically: Scripts \scripts\... Core code \lib\site-packages\roundup\... Support files \share\roundup\... and on Unix-like systems (eg. Linux): Scripts /bin/... Core code /lib-/site-packages/roundup/... Support files /share/roundup/... 2. The installation of a specific tracker. When invoking the roundup-admin "inst" (and "init") commands, you're creating a new Roundup tracker. This installs configuration files, HTML templates, detector code and a new database. You have complete control over where this stuff goes through both choosing your "tracker home" and the DATABASE variable in config.py. Users and Security ================== Roundup holds its own user database which primarily contains a username, password and email address for the user. Roundup *must* have its own user listing, in order to maintain internal consistency of its data. It is a relatively simple exercise to update this listing on a regular basis, or on demand, so that it matches an external listing (eg. unix passwd file, LDAP, etc.) Roundup identifies users in a number of ways: 1. Through the web, users may be identified by either HTTP Basic Authentication or cookie authentication. If you are running the web server (roundup-server) through another HTTP server (eg. apache or IIS) then that server may require HTTP Basic Authentication, and it will pass the ``REMOTE_USER`` variable through to Roundup. If this variable is not present, then Roundup defaults to using its own cookie-based login mechanism. 2. In email messages handled by roundup-mailgw, users are identified by the From address in the message. In both cases, Roundup's behaviour when dealing with unknown users is controlled by Permissions defined in the "SECURITY SETTINGS" section of the tracker's ``dbinit.py`` module: Web Registration If granted to the Anonymous Role, then anonymous users will be able to register through the web. Email Registration If granted to the Anonymous Role, then email messages from unknown users will result in those users being registered with the tracker. More information about how to customise your tracker's security settings may be found in the `customisation documentation`_. Tasks ===== Maintenance of Roundup can involve one of the following: 1. `tracker backup`_ 2. `software upgrade`_ 3. `migrating backends`_ 4. `moving a tracker`_ Tracker Backup -------------- Stop the web and email frontends and to copy the contents of the tracker home directory to some other place using standard backup tools. Software Upgrade ---------------- Always make a backup of your tracker before upgrading software. Steps you may take: 1. ensure that the unit tests run on your system 2. copy your tracker home to a new directory 3. follow the steps in the upgrading documentation for the new version of the software 4. test each of the admin tool, web interface and mail gateway using the new version of the software 5. stop the production web and email frontends 6. perform the upgrade steps on the existing tracker directory 7. upgrade the software 8. restart your tracker Migrating Backends ------------------ 1. stop the existing tracker web and email frontends (preventing changes) 2. use the roundup-admin tool "export" command to export the contents of your tracker to disk 3. copy the tracker home to a new directory 4. change the backend used in the tracker home ``select_db.py`` file 5. delete the "db" directory from the new directory 6. use the roundup-admin "import" command to import the previous export with the new tracker home 7. test each of the admin tool, web interface and mail gateway using the new backend 8. move the old tracker home out of the way (rename to "tracker.old") and move the new tracker home into its place 9. restart web and email frontends Moving a Tracker ---------------- If you're moving the tracker to a similar machine, you should: 1. install Roundup on the new machine and test that it works there, 2. stop the existing tracker web and email frontends (preventing changes), 3. copy the tracker home directory over to the new machine, and 4. start the tracker web and email frontends on the new machine. Most of the backends are actually portable across platforms (ie. from Unix to Windows to Mac). If this isn't the case (ie. the tracker doesn't work when moved using the above steps) then you'll need to: 1. install Roundup on the new machine and test that it works there, 2. stop the existing tracker web and email frontends (preventing changes), 3. use the roundup-admin tool "export" command to export the contents of the existing tracker, 4. copy the export to the new machine, 5. use the roundup-admin "import" command to import the tracker on the new machine, and 6. start the tracker web and email frontends on the new machine. ------------------- Back to `Table of Contents`_ .. _`Table of Contents`: index.html .. _`customisation documentation`: customizing.html