File: $Id: upgrade.txt,v 1.16 2005/06/01 01:50:40 jill Exp $ Description: Ozibug upgrade notes Date: 01 June 2005 Introduction ------------ These notes explain how to upgrade a default Ozibug installation. It specifies the files and locations that are used and their purpose. Data Format and Versions ------------------------ There is no special requirement on the data files and their format when upgrading from a previous version. The application will update any necessary properties and attributes as necessary. Note: Version 2.X has a different user repository format than previous versions. Instead of a single file (users.xml) there is now a directory (users) containing multiple files. When Ozibug 2.X starts it will automatically create the new directory, and convert the single file to multiple files, moving the original file after successful conversion. Directory Structure ------------------- By default the Ozibug application will have a file structure similar to the following. ozibug index.html - html index file # images - application images stylesheets - css stylesheets WEB-INF - servlet data directory lib - ozibug runtime jar and additional jar files classes - runtime directory ? *.properties - language properties files ? templates - html templates ! relnotes - release notes templates * bugs - bugs data directory * preferences - user preferences data directory tmp - temporary application files directory * reference.xml - reference data definitions * users - user definitions (version 2.X) * users.xml - user definitions (version 1.X) + ozibug.properties - application configuration License.ser - license file web.xml - servlet configuration The files and directories marked with an asterisk (*) contain application specific data and must be retained. The directories marked with a bang (!) contain customized release notes templates specific to your installation. These custom files should be retained for use in thew new version. The files marked with a plus (+) contain configuration information specific to your installation - you will want to apply this configuration to the new file. The files marked with a question mark (?) are html templates and locale specific properties. If you have made any changes to these files then these changes must be re-applied to the files supplied with the new version. If you have added any new templates (eg., custom headers or footers) then these custom files should be retained for use in the new version. The files marked with a hash (#) are images. If you have added any new images (eg., logos) then these custom files should be retained for use in the new version. Users without current support must obtain a new license for this version from http://www.ozibug.com/ Upgrade Instructions -------------------- The following instructions outline the steps of the upgrade process. 1. Shutdown the Servlet Container 2. Move the existing Ozibug directory structure to an archive location. 3. Unzip the new Ozibug war file into place 4. Copy across the following data files and directories from the archive ozibug/WEB-INF/bugs - bug data ozibug/WEB-INF/preferences - user preferences ozibug/WEB-INF/reference.xml - reference data ozibug/WEB-INF/users - user data (version 2.X) ozibug/WEB-INF/users.xml - user data (version 1.X) ozibug/WEB-INF/templates/notifications - mail notification templates ozibug/WEB-INF/templates/relnotes - release notes templates NOTE: if upgrading from 1.X to 2.X you must also remove the distributed ozibug/WEB-INF/users directory (see the Data Format and Versions section above.) 5. Update the new ozibug/WEB-INF/ozibug.properties file with any changes you made (log files, mailServer, locale) to the previous version. 6. If you made any changes to the html template files contained in the ozibug/WEB-INF/templates directory - you will need to re-apply these changes to the new files. 7. If you added any custom html template files (eg., headers or footers) to the ozibug/WEB-INF/templates directory - you will need to copy these files across from the archive. 8. If you made any changes to the language properties files contained in the ozibug/WEB-INF/classes directory - you will need to re-apply these changes to the new files. 9. If you added any custom image files (eg., logos) to the ozibug/images directory - you will need to copy these files across from the archive. 10. Copy your new license into the ozibug/WEB-INF directory. 11. Startup the Servlet Container. Split Installation ------------------ You can re-arrange the layout of the Ozibug servlet to separate the data from the application. This allows a system administrator control over the location of the data (perhaps for speed, perhaps for backup purposes) which also increases the ease of an upgrade process. The following example shows a Unix Platform which has split the ozibug servlet directory into two pieces, the servlet and the data. /webapps/ozibug index.html - html index file doc - local copy of documentation images - application images stylesheets - css stylesheets WEB-INF - servlet data directory lib - ozibug runtime jar and additional jar files classes - runtime directory templates - html templates notifications - mail notification templates relnotes - release notes templates web.xml -> /data/ozibug/WEB-INF/web.xml - symbolic link to data directory web.xml (custom version) /data/ozibug logs - log directory WEB-INF - servlet data directory bugs - bugs data directory preferences - user preferences data directory tmp - temporary application files directory License.ser - license file reference.xml - reference data definitions users.xml - user definitions (version 1.X) users - user definitions (version 2.X) ozibug.properties - application configuration web.xml - servlet configuration (custom version) The following modifications must be made in order for this to work. web.xml ------- Change the configuration of the properties file to point to the data directory ... system.properties.filename /data/ozibug/WEB-INF/ozibug.properties ... ozibug.properties ----------------- Change the following properties to point to the data directories and files. ... log.debug.filename=/data/ozibug/logs/debug.log log.audit.filename=/data/ozibug/logs/audit.log ... license.filename=/data/ozibug/WEB-INF/License.ser ... tmp.directory=/data/ozibug/WEB-INF/tmp ... You will also need to add the following properties which point the repositories at the exact files and directories. ... user.xmlrepository.path=/data/ozibug/WEB-INF preference.xmlrepository.path=/data/ozibug/WEB-INF reference.xmlrepository.filename=/data/ozibug/WEB-INF/reference.xml bug.xmlrepository.path=/data/ozibug/WEB-INF ... Note: The Ozibug version 1.X property user.xmlrepository.filename has been replaced by the new, version 2.X property user.xmlrepository.path This property will be replaced automatically by Ozibug when upgrading from a previous version. You do not need to add this property. A similar installation can be carried out on the Win32 platform, the only difference is that as there are no symbolic links the web.xml must be located in the servlet directory rather than the data directory. Care must then be taken not to overwrite this file on installation. C:\webapps\ozibug index.html - html index file doc - local copy of documentation images - application images stylesheets - css stylesheets WEB-INF - servlet data directory lib - ozibug runtime jar and additional jar files classes - runtime directory templates - html templates notifications - mail notification templates relnotes - release notes templates web.xml - servlet configuration (custom version) C:\data\ozibug logs - log directory WEB-INF - servlet data directory bugs - bugs data directory preferences - user preferences data directory tmp - temporary application files directory License.ser - license file reference.xml - reference data definitions users - user definitions (version 2.X) users.xml - user definitions (version 1.X) ozibug.properties - application configuration Again the following modifications must be made in order for this separation to work. web.xml ------- Change the configuration of the properties file to point to the data directory ... system.properties.filename C:\data\WEB-INF\ozibug.properties ... ozibug.properties ----------------- Change the following properties to point to the data directories and files. ... log.debug.filename=C:\data\ozibug\logs\debug.log log.audit.filename=C:\data\ozibug\logs\audit.log ... license.filename=C:\data\ozibug\WEB-INF\License.ser ... tmp.directory=C:\data\ozibug\WEB-INF\tmp ... Again you'll will also need to add the following properties which point the repositories at the exact files and directories. ... user.xmlrepository.path=C:\data\ozibug\WEB-INF preference.xmlrepository.path=C:\data\ozibug\WEB-INF reference.xmlrepository.filename=C:\data\ozibug\WEB-INF\reference.xml bug.xmlrepository.path=C:\data\ozibug\WEB-INF ... Note: The Ozibug version 1.X property user.xmlrepository.filename has been replaced by the new, version 2.X property user.xmlrepository.path This property will be replaced automatically by Ozibug when upgrading from a previous version. You do not need to add this property.