============================================================================================ QuickBuild-1.2.12 readme ============================================================================================ IMPORTANT INFORMATION -------------------------------------------------------------------------------------------- 1. This version requires JDK 1.5 (If you want to run QuickBuild on JDK1.4, please download distro "quickbuild-xxx-jdk14.zip" or "quickbuild-xxx-jdk14.tar.gz" instead. This document assumes that you are running QuickBuild on top of JDK1.5, but it also applies to JDK1.4). 2. Permanent license for 1.0.x and 1.1.x will fall back to the 30 days trial license after upgrade to 1.2.x. However, existing customer can self-generate the new license using the service account at our web site (www.pmease.com). System requirements -------------------------------------------------------------------------------------------- 1. Operating system: Windows 2000/XP/Vista, Linux, Solaris, MacOS (running on other type of operating system has not been tested yet. However, as a 100% pure Java application, it may run on any OS with JDK 1.5 support). 2. Physical memory: 256M minimum, 512M recommended. 3. Web browser: Internet explorer 6.x or Firefox 1.x, with javascript and cookie enabled. Installation guide -------------------------------------------------------------------------------------------- 1. Make sure you have JDK 1.5 installed. Go to "http://java.sun.com/" for JDK 1.5 download, if you didn't install it yet. Also the environment variable JAVA_HOME need to be defined to point to JDK home directory (the directory containing bin, lib,...). 2. Extract quickbuild-1.2.12.zip or quickbuild-1.2.12.tar.gz. After extraction, a directory "quickbuild-1.2.12" will be created. Some important directories contained in this directory: 1) api: libraries, samples, and JavaDoc of QuickBuild remote API. 2) bin: executables used to start/stop QuickBuild, and package QuickBuild web application. 3) data: the embeded HSQLDB database. 4) docs: QuickBuild user manual and JavaDoc. 5) logs: QuickBuild system wide logs. 6) publish: default global publish directory. 7) templates: various velocity templates used to define notifiers. 8) tomcat: embeded tomcat distribution. 9) web: default QuickBuild web application folder. 10) working: default global working directory. 3. Make sure port 8080 is not used by any other applications. Change to "bin" sub directory under "quickbuild-1.2.12". 1) If you are installing QuickBuild on Windows platform, run "startup.bat" to start QuickBuild, or run "shutdown.bat" to stop QuickBuild. 2) If you are installing QuickBuild on UNIX-like platform, make sure the account used to start QuickBuild has full access to directory "quickbuild-1.2.12" and its sub directories. Run "startup.sh" to start QuickBuild, or run "shutdown.sh" to stop QuickBuild. Make sure there are no errors printed out in the console. 4. Access QuickBuild web interface from http://:8080, where should be replaced by computer name or ip address of the server running QuickBuild. 5. QuickBuild displays several pages to help you set up some basic parameters and after that, you can start to use QuickBuild. User name of administrator is "admin", password is initially "admin", and can be changed in file "quickbuild-1.2.12/config.propreties". Upgrade from old versions -------------------------------------------------------------------------------------------- 1. If you are using MySQL or SQL Server as database, edit file "config.properties" to connect to your existing database. 2. If you are using HSQLDB as database, copy "data" sub directory from existing installation to QuickBuild 1.2.12. 3. Copy "publish" sub directory from existing installation to QuickBuild 1.2.12. 4. For users who upgrade from 1.0.x or 1.1.x, please be noted that: 1) If you are using Accurev repository and have set the reference tree property as empty, please give it the value of ${this.generateReferenceTreeName()}. 2) The directory used to hold checked out code from Accurev is changed to current configuration's checkouts directory (instead of determined by calling ${repository["accurev_repository"].getWorkspaceDir(build)}). This may affect the builder definition which relies the checked out build script. 3) The file name pattern separator has been changed from space to comma when define QuickBuild modules of a QuickBuild repository. The quotes should be removed if you are using it to quote a single pattern including spaces. 4) File name pattern separator has been changed from space to comma when define the publish step. The quotes should be removed if you are using it to quote a single pattern including spaces. 5) All promote destination properties specified in basic settings of the configuration is now inherited from parent configuration if the value is left empty. Previously the remote QuickBuild URL property is default to current QuickBuild system if it is left empty. 6) The URL to build artifact is now using build id instead of configuration name and build version. Refer to the appendix explaining artifact URL in the user guide. 7) Remote QuickBuild URL property of the QuickBuild repository is now a required property. To specify current QuickBuild system, please specify the value "${system.url}" (without quotes). 5. For users who upgrade from versions prior to 1.2.3, please be noted that: 1) Users with build permission will not able to specify build version and variable values when trigger build. 2) Users with build permission will not able to specify promote version and variable values when promote build. 3) Multiple promote destinations can now be defined for a particular configuration. Users need to redefine their promote destinations using the new format. Use other databases other than the embedded HSQLDB -------------------------------------------------------------------------------------------- 1. Do a backup of current database through "administration" tab, so that the backed up data can be restored into your new database later. Of course this step is not necessary if you do not want to migrate data in current database. 2. Modify "config.properties" to connect to your desired database. Currently the following databases other than HSQLDB are supported: 1) MySQL 2) Microsoft SQL Server 3. Restore the database through "administration" tab, using backed up file in step 1. This step is not necessary if you do not want to migrate data. WARNING: Do not connect multiple QuickBuild instances to the same database. Use other application servers other than shipped Tomcat -------------------------------------------------------------------------------------------- 1. Change to "bin" sub directory, and run command "war.bat" (or "war.sh" in Unix-like systems). The file "quickbuild.war" will be generated in QuickBuild's installation directory. 2. Deploy "quickbuild.war" into your choosed application server by following your application server's instructions. Note that the URL to access QuickBuild may be different, and it depends on how you deploy "quickbuild.war". QuickBuild has been tested with the following application servers: 1) Tomcat 4.x, Tomcat 5.x 2) Resin 3.x 3. QuickBuild may work with other application servers (must support Servlet 2.3), but has not been tested. Migrate data from Luntbuild 1.5.x, 1.4.x, 1.3.x and 1.2.x -------------------------------------------------------------------------------------------- 1. Start up Luntbuild, and export data into "data.xml" under Luntbuild installation directory. 2. Login to QuickBuild as "admin", change to "administration" tab, and select "Migrate from Luntbuild". 3. During the migration, all build artifacts will be picked up from your existing Luntbuild instance and modified to be compatible with QuickBuild's artifacts structure, and put under the "publish" sub directory of QuickBuild. This may take a long time if you have many many builds, so be patient... 4. If you just want to migrate configuration data (such as projects, schedules), but not build artifacts, you can simply select "Restore database" menu item, and specify path to "data.xml" created in step 1. 5. After the migration, please be aware of the following things: 1) OGNL expressions used in "next build version", "build properties", and "build environments" are not migrated. You should make sure they conform to new OGNL expressions described in Chapter 4 in the user guide. 2) Project dependencies are not migrated, cause dependency mechanism in QuickBuild is very different from Luntbuild. You need to understand the new dependency mechanism and get them re-configured. 3) Properties such as "build necessary condition" and "build success condition" have been reset to conform to new format of QuickBuild. You can customize them further to fit your needs. 4) If you are using UCM ClearCase repository, please edit this repository to set correct value for property "baselines". The "what to build" property you configured in previous versions is now removed. 5) MKS adapter and Clearcase dynamic adapter is not migrated as QuickBuild does not support them currently. 6) LDAP settings are not migrated. You need to re-configure LDAP settings through menu "Administration->Authenticators". 7) If migrated from Luntbuild 1.5.x, web interface and web url property of various SCMs will be ignored. 8) If migrated from Luntbuild 1.5.x, layout property of Subversion SCM will be ignored. ============================================================================================ Thanks for using QuickBuild. Any problem or suggestion, please visit http://www.pmease.com/Support.page ============================================================================================