Viewtier Parabuild 4.3. Installation Guide

Transcription

1 Viewtier Parabuild 4.3 Installation Guide

2 Viewtier Parabuild 4.3: Installation Guide Copyright Viewtier Systems

3

4 Table of Contents Preface... vi About This Manual... vi Audience... vi Technical Support... vi 1. Installing Parabuild System Requirements... 2 Default Installation Directory... 2 CPU... 2 Quantity of CPUs... 2 Size of RAM... 2 Disk Space... 2 Disk Speed... 3 Networking Installing Parabuild Under Windows... 4 Starting Parabuild Service... 4 Stopping Parabuild Service... 5 Managing Parabuild Service from Program Group... 5 Post-Installation Actions... 5 ClearCase Considerations... 5 Devenv Considerations... 5 Visual SourceSafe Considerations... 5 Adjusting Memory Size... 6 Disabling Antivirus Software... 6 Changing Parabuild Service User Installing Parabuild Under Linux... 7 Installing From Binary Distribution... 7 Disabling Setting User of Working Build Directories... 7 Installing From tar.gz Archive Installing Under Solaris Installing Under Mac OS X... 9 Prerequisites... 9 Installing From Binary Distribution... 9 Starting Parabuild Daemon... 9 Stopping Parabuild Daemon Installing under Generic Unix Installing Java SDK Installing Parabuild From Generic Unix Distribution Adjusting Startup Scripts Starting and Stopping Parabuild Upgrading Configuring builds Running Parabuild in Remote Builder Mode Prerequisites Windows XP Installing Parabuild in Remote Builder Mode Enabling Running Build Agent as Administrator Under Windows Hard-to-guess Installation Problems Error "No X11 DISPLAY variable was set" Build Server Security Implications iv

5 List of Examples 7.1. Starting Parabuild Service Under Linux Stopping Parabuild Under Linux Upgrading Parabuild Under Solaris Fragment of parabuild.conf for Parabuild running in remote agent mode Fragment of parabuild.conf for Parabuild running as Administrator in remote agent mode 16 v

6 Preface About This Manual This document provides the information you need to install and configure a Viewtier Parabuild server as a stand-alone server or as a remote agent. Viewtier Parabuild (Parabuild) is an automated multi-platform software build management server. Parabuild provides automatic (integration) and scheduled builds. Automatic builds are fired upon every check-in or a group of check-ins into a project source line. Scheduled builds are fired at a configured time. Audience This guide is intended for anyone who is installing a Parabuild server or a remote agent on a computer running a supported version of Microsoft Windows, Linux or Unix. It assumes a basic knowledge of corresponding operating systems and their conventions. Technical Support If you have any problems with the software or documentation, please contact Viewtier Technical Support via online support forums, electronic mail, fax, or as described below. For information regarding other support information, click the Support link on the Viewtier Web site at [ Support Forum: Electronic Mail: support@viewtier.com [mailto:support@viewtier.com] Fax: vi

7 Chapter 1. Installing Parabuild Parabuild distribution is available for many operating systems, including Windows, Linux, Solaris, Mac OS X, and other flavors of Unix. Following chapters talk about installing Parabuild for the specific operating systems. We assume that you have already downloaded a version suitable for your operating system. The average time to install Parabuild, including post-installation tasks, is about five minutes. 1

8 Chapter 2. System Requirements Parabuild is an integral part of the Application Lifecycle Management (ALM) infrastructure. A typical ALM infrastructure consists of a version control system, a bug or an issue tracking system, and a build server. Software build processes such as Continuous Integration and daily builds are highly IO, memory and computationally intensive. Dedicating adequate resources to Parabuild ensures efficient software development. Default Installation Directory CPU A default installation directory under Windows is C:\parabuild. A default installation directory under Unix is /opt/parabuild. Build processes are usually dependent on the CPU. CPU speed for Parabuild should be at least equal to the speed of the fastest development machine. A better approach here would be to obtain the fastest CPU your budget could afford. Faster builds produce quicker feedback, thus providing greater timing and financial savings. Quantity of CPUs It is essential that Parabuild runs on a dedicated multiprocessor system. Multiprocessor systems are better suited to perform multiple computationally intensive tasks that build processes are. The quantity of CPUs depends on the number of the build configurations and percentage of time each build runs. It can be estimated as the sum of the total build time percentage divided by one hundred and rounded to the next two, four, eight, 16, or 32. For example, if Parabuild runs eight builds and each build runs 20% of the time, the quantity of CPUs needed for the server is two. Size of RAM Selecting the adequate size of the build server's RAM is important. In case of low physical memory builds can be slow because of swapping. The minimum amount of RAM can be estimated as the sum of RAM need to run each build plus RAM needed by a version control client running full checkout plus RAM needed by the operating system and system processes. We recommend multiplying the result by 1.2 coefficients to offset unaccounted factors. Example: let OS RAM is 120Mb, each build run needs 100Mb, and each client needs 1Mb. The minimal size of RAM is going to be (120Mb + 8*100Mb + 8*1Mb) * 1.2 = 1,113.6Mb or roughly 1Gb. Disk Space Free disk space needed on Parabuild machine depends on the number of build configurations, the number of build runs per day, and the size of build artifacts to be placed in the build archive after each build run. The estimated size of the needed free disk space in megabytes may be calculated by using this formula Sz = (Nbuilds * 2 * Bsize) + (Nbuilds * NRuns *Asize * 3 *365) Where Sz is minimum required disk space, Nbuilds is a quantity of build configurations, Bsize is disk 2

9 System Requirements space occupied by the code base, Nruns is a number of times build runs a day, Asize is disk space occupied by results placed in build archive. Example: consider a build server running 4 build configurations, each code base taking 200Mb when checked out; each build runs 10 times a day and stores 5Mb of logs and build artifacts each time; an archived items should be stored for a year. The estimated minimum disk space needed for this configuration would be 220,600Mb = 4*2*200Mb + 4*10*5Mb*3*365 Disk Speed Speed of the disk subsystem is an important factor affecting overall performance of a build server. Build processes are I/O intensive and more read than write oriented. Typical writes/reads ratios range from 2 to 5. We recommend using a high-speed 10,000 or 15,000 rpm SCSI RAID-1 array under management of a quality RAID controller. RAID-1 provides high-speed concurrent reads and writes while maintaining reliability of the disk subsystem. We do not recommend using RAID-5 because of its significantly slower write speeds. If a high speed SCSI RAID-1 is not an option because of budget concerns, 7200 rpm IDE RAID-1 is a minimal configuration. Networking Parabuild listens on port Certain applications and services such as Tomcat and Apache may also listen on port This may prevent Parabuild from starting up correctly. Make sure that no other services listen on port It is important that Parabuild is connected to the rest of the ALM infrastructure through a high-speed local area network (LAN). Parabuild accesses a version control system to create local copies of the projects' code base to build and query for the latest changes. It can also access the issue tracking system to obtain release notes. Slow or congested LAN may significantly increase build roundtrip time if the size of the code base is significant (hundreds of megabytes). Ideally, Parabuild should be connected to the same network switch as the version control server is. 3

10 Chapter 3. Installing Parabuild Under Windows For Windows, a single Parabuild setup program is available. In order to begin installation, type this command in the Windows command prompt: parabuild_4_3_windows.exe This will launch a graphical user interface (GUI) installer that will lead you through the rest of the installation process. As a part of the installation process, the set up program will offer to select a destination directory for Parabuild. The default directory is C:\parabuild. You can change it if necessary. We recommend leaving it as is. Note When installing Parabuild, please avoid using directories containing spaces or long names. After the installation is complete, a program group named "Parabuild" will appear in your Programs menu. The program group contains links to installed Parabuild documentation. Starting Parabuild Service Parabuild is installed as a Windows service and is started automatically when the installation is complete. Parabuild service starts automatically when the Windows system is re-started. It is possible to start Parabuild service manually if it is not running, for example because it was stopped before. To start Parabuild from the command line, follow the steps below: 1. Press the "Start" button; 2. Click on "Run" menu item; 3. Type "cmd" in the "Open" field, a command shell will open; 4. Type "net start parabuild". This command will start Parabuild service. It is also possible to start Parabuild service using administrative interface: 1. Press the "Start" button; 2. Click on "Settings" menu item, Windows control panel will open; 3. Click on "Administrative Tools" icon; 4. Click on "Services" icon, Services management window will open; 5. Find Parabuild in the list of services, right click on it, select "Start". Parabuild service will start. 4

11 Installing Parabuild Under Windows Stopping Parabuild Service It is possible to stop Parabuild service manually, for example to perform an upgrade. To stop Parabuild from the command line, follow the steps below: 1. Press the "Start" button; 2. Click on "Run" menu item; 3. Type "cmd" in the "Open" field, a command shell will open; 4. Type "net stop Parabuild". This command will stop Parabuild service. It is also possible to stop Parabuild service using administrative interface: 1. Press the "Start" button; 2. Click on "Settings" menu item, Windows control panel will open; 3. Click on "Administrative Tools" icon; 4. Click on "Services" icon, Services management window will open; 5. Find Parabuild in the list of services, right click on it, select "Stop". Parabuild service will stop. Managing Parabuild Service from Program Group In addition to using Windows Services to manage Parabuild service, Parabuild allows to start and stop Parabuild service directly from Parabuild program group: Post-Installation Actions Some environments require manual actions to be taken after the installation of Parabuild is completed. Below you can find considerations for such environments. ClearCase Considerations To access ClearCase, a user that Parabuild service runs as should be changed from a default user to a valid domain user. Please check section Changing Parabuild Service User for instructions. Devenv Considerations For devenv to function properly, a user that Parabuild service runs as should be changed from a default user to a valid domain user. Please check section Changing Parabuild Service User for instructions. Visual SourceSafe Considerations To access Visual SourceSafe, a user that Parabuild service runs as should be changed from a default user to a valid domain user. Such user should have adequate rights to access a Visual SourceSafe database on 5

12 Installing Parabuild Under Windows your network. Please check section Changing Parabuild Service User for instructions. Adjusting Memory Size The default size of the memory allocated to Parabuild is 60 Megabytes. This value maybe too low for some environments. Under Windows, it is possible to change this value to a higher number. To change the size of the memory avalable to Parabuild, edit file parabuild.vmoptions under bin directory and chage option -Xmx60m. For example, to allocate 500 Megabytes to Parabuild, this option should be equal -Xmx500m. Parabuild service needs to be restarted for changes to take effect. Disabling Antivirus Software Viewtier Systems recommends disabling antivirus software for the directory where Parabuild is installed. Running antivirus software on Parabuild installation may cause significant degradation of performance. If complete disabling of antivirus software is impossible, the following directory should be excluded from antivirus scanning: <Parabuild home>/etc/data. Changing Parabuild Service User By default, Parabuild service runs as a user with name "LocalSystem". Certain version control and build scripting systems require their clients to run as a domain user rather than "LocalSystem". To change a user Parabuild service runs as, follow the steps below: 1. Press the "Start" button; 2. Click on "Settings" menu item, Windows control panel will open; 3. Click on "Administrative Tools" icon; 4. Click on "Services" icon, Services management window will open; 5. Find Parabuild in the list of services, right click on it, select "Properties" menu item; 6. Select "Log On" tab; 7. Select "This account" radio button. 8. Enter a user name, an optional domain name and a password. 9. Press "OK" button. 10. Stop and start Parabuild service to activate the changes. Important When changing a user under Windows Server 2003, use format DOMAIN\user. 6

13 Chapter 4. Installing Parabuild Under Linux In order to install Parabuild, you need to log in as a root. It is necessary because the Parabuild installer will create a daemon that will start upon the build box startup. Also, post-installations tasks for Parabuild may require root privileges. Installing From Binary Distribution The installation of Parabuild is simple. To install Parabuild, start a shell, cd to a directory where installer file is located and type this command: sudo mkdir /opt/parabuild sudo sh parabuild_4_3_linux.sh -q Please note using "-q" switch. This switch asks Parabuild installer not to launch the installation process in a graphical mode. We recommend to use this switch whenever Parabuild installation is performed from a remote terminal. Once the installer finishes the execution, Parabuild is installed in the / opt/parabuild directory. Disabling Setting User of Working Build Directories When upgrading, Parabuild automatically changes the ownership of working build directories to user parabuild to ensure that the build directories have a proper ownership. While this is the safest mode of installing an upgrade, the operation of changing the user can be time consuming on bigger working build directories. To disable changing the user, use option -Dparabuild.chown.build.dirs=no. sudo mkdir /opt/parabuild sudo sh parabuild_4_3_linux.sh -q -Dparabuild.chown.build.dirs=no Installing From tar.gz Archive Installing Parabuild from tar.gz archive consists of creating a Parabuild installation directory and extracting the Parabuild distribution to the installation directory using the tar archiving utility. Start a shell and execute the following commands: mkdir /opt/parabuild tar -Zxf parabuild_4_3_linux.tar.gz -C /opt To complete installation, please proceed to the Post-installation Tasks chapter. 7

14 Chapter 5. Installing Under Solaris Note Parabuild installation creates a home directory for parabuild user under /home. Newly installed Solaris 9 and 10 systems may not allow to do so because /home is controlled by the automounter. Before installing make sure that /home is not under the control of automountd. Either edit the / etc/auto_master or /etc/auto_home or stop the automountd service from running. To install Parabuild, start a shell, cd to a directory where installer file is located and type this command: sudo mkdir /opt/parabuild sudo sh parabuild_4_3_solaris.sh -q When installer finishes execution, Parabuild is installed in /opt/parabuild directory. 8

15 Chapter 6. Installing Under Mac OS X Prerequisites Parabuild is installed on Mac OS X 10.2.x ("Jaguar") and up using a Mac OS X binary package in PKG format. Please note that older versions of Mac OS X (for example, 10.1.x) are not supported by this package. To be installed on Mac OS X, Parabuild requires that Java SDK version is available on a machine that will run Parabuild. Important If you are upgrading Parabuild, first stop Parabuild daemon and perform a full back up of the Parabuild installation directory. Installing From Binary Distribution The installation of Parabuild from binary distribution is simple. To install Parabuild, start a terminal, cd to a directory where installer file is located and type this command: sudo sh parabuild_4_3_mac_osx.sh -q Please note using "-q" switch. This switch asks Parabuild installer not to launch the installation process in a graphical mode. We recommend to use this switch whenever Parabuild installation is performed from a terminal. Once the installer finishes the execution, Parabuild is installed in the / usr/local/parabuild directory. Starting Parabuild Daemon Parabuild is installed as a Mac OS X startup item. To start Parabuild daemon manually if it is not running follow the steps below: 1. Open Terminal. 2. Type sudo /Library/StartupItems/Parabuild/Parabuild start 3. Enter su's password Parabuild daemon starts automatically when the Mac OS X system is re-started. Stopping Parabuild Daemon To stop Parabuild daemon manually if it is running follow the steps below: 9

16 Installing Under Mac OS X 1. Open Terminal. 2. Type sudo /Library/StartupItems/Parabuild/Parabuild stop 3. Enter su's password 10

17 Chapter 7. Installing under Generic Unix Currently Parabuild distribution packages for the following operating systems do not require installation of additional software: 32-bit Windows x86, 32-bit Linux x86, Solaris Sparc and HP-UX 11 PA-RISC. To be installed on other Unix flavors such as FreeBSD, Parabuild requires that Java SDK version is available on a machine that will run Parabuild. A generic Unix Parabuild distribution should be used for such operating systems. Installing Parabuild from generic distribution consists of installing Java SDK version 1.4.2, installing Parabuild itself, and adjusting the Parabuild startup scripts to point to Java SDK location. These steps are considered in detail below. Installing Java SDK If you do not have Java SDK already installed, download it and install it with the following installation instructions provided by your Java SDK vendor. Make a record of Java SDK installation home. For instance, it may look like /opt/j2sdk1.4.2_03. Installing Parabuild From Generic Unix Distribution To install Parabuild, start a shell, cd to a directory where installer file is located and type this command: sudo mkdir /opt/parabuild sudo sh parabuild_4_3_generic_unix.sh -q When installer finishes execution, Parabuild is installed in /opt/parabuild directory. Adjusting Startup Scripts Parabuild startup scripts need to know the location of the Java SDK. Go to /opt/parabuild/bin directory and modify parabuild.sh and parabuild shell scripts by adding the following lines right after the header comment lines: JAVA_HOME=<path to Java installation home> export JAVA_HOME If Java is installed in /opt/j2sdk1.4.2_03, the added line would look like this: JAVA_HOME=/opt/j2sdk1.4.2_03 export JAVA_HOME To complete the installation, please proceed to Unix Post-installation Tasks chapter. Starting and Stopping Parabuild 11

18 Installing under Generic Unix Once the installation is complete and secured, you can start or stop Parabuild service using the created daemon commands according to the paths to startup scripts for the target operating system. Example 7.1. Starting Parabuild Service Under Linux /etc/init.d/parabuild start Example 7.2. Stopping Parabuild Under Linux /etc/init.d/parabuild stop Note Normally Parabuild runs a few external process, so clearing them up may take few seconds. 12

19 Chapter 8. Upgrading Important Always stop the Parabuild server before upgrading. Performing an upgrade operation while the Parabuild server is running may render it unusable. Important Always perform a full back up of the Parabuild installation before upgrading. Though the Parabuild installer handles upgrade tasks automatically, unforeseen conditions may hinder the installation process and leave Parabuild installation in a incomplete state. To upgrade, just run the binary installer for the targeted operating system. Parabuild installation process will preserve all modifications. Example 8.1. Upgrading Parabuild Under Solaris sudo sh parabuild_4_3_solaris_sparc.sh -q 13

20 Chapter 9. Configuring builds After you have completed installation and started Parabuild, you may begin configuring builds. You should be able to access. Suppose you installed Parabuild at a machine with the network name BUILD. Then you would be able to access Parabuild at the URL A public build status page would be available for the members of your engineering team at the URL The default administrative password is "admin". Parabuild Administrator's Guide describes build administration in detail. 14

21 Chapter 10. Running Parabuild in Remote Builder Mode Prerequisites Windows XP Parabuild uses a custom protocol to access remote builders. Parabuild needs port number 8080 open on a Windows XP machine. If this is a stock Windows XP, the firewall is on and the port is closed. Open the port. After installing Parabuild in the remote agent mode, make sure you can telnet port 8080 on the XP machine from the build manager machine. Installing Parabuild in Remote Builder Mode Parabuild can run in two modes: as a build manager mode or as remote agent. By default the Parabuild installation is set to run in the build manager mode. This chapter describes actions that need to be taken to set Parabuild up to run in a remote agent mode. Build manager mode In the build manager mode Parabuild: Serves web user interface requests. Maintains build archive Runs local and remote builds Sends build notifications. Remote agent mode In addition to running builds locally, Parabuild can run builds remotely on machines other than the one the build manager is installed on. Running builds remotely may offer the following benefits: Remote builds allow to run builds on a variety of platforms yet to have an access to the build results at a single entry point (build manager). Remote builds allow to partition the load by moving CPU and IO load off the build manager. Remote builds allow to create more secure build infrastructure so that build scripts are not executed at the build manager box. To set up Parabuild to run as a remote agent, follow the standard installation procedure described earlier. Once the installation is complete, modify the Parabuild configuration file <Parabuild installation directory>/etc/system/parabuild.conf. Modify or set the property parabuild.build.manager.ipaddress in the configuration file by assigning an IP address of the machine running Parabuild in the build manager mode. With parabuild.build.manager.ipaddress set Parabuild will start in the remote agent mode. 15

22 Running Parabuild in Remote Builder Mode Example Fragment of parabuild.conf for Parabuild running in remote agent mode parabuild.build.manager.ipaddress= A build manager can run builds on multiple remote builders. A remote agent will serve as single build manager with the configured IP address only. The remote agent will accept requests coming from local addresses only, i.e. those starting with *, 10.*, *, * and Enabling Running Build Agent as Administrator Under Windows Some environments require running a remote build agent as Administrator user. Before, Parabuild prohibited this configuration. Parabuild 4.0 introduced an ability to enable the remote build agent to run as Administrator by adding the following line to the Parabuild configuration file <Parabuild installation directory>/etc/system/parabuild.conf on the remote build agent: Example Fragment of parabuild.conf for Parabuild running as Administrator in remote agent mode parabuild.allow.administrator.user=true Parabuild service on the remote agent machines needs to be restarted to activate the change. 16

23 Chapter 11. Hard-to-guess Installation Problems This chapter covers some environment-dependent installation problems that can be hard to resolve by applying common sense. Error "No X11 DISPLAY variable was set" Parabuild installer can throw an exception "No X11 DISPLAY variable was set, but this program performed an operation which requires it" when the graphical installer (default mode) is run from a remote terminal without X support. The solution is to run the installer using batch mode with the -q switch: sudo mkdir /opt/parabuild sudo sh parabuild_4_3_linux.sh -q 17

24 Chapter 12. Build Server Security Implications Security implications of running a build server are significantly different from ones for other components of the software change management (SCM) infrastructure, namely version control systems and the issue or bug trackers. What the control users of such servers have is usually limited to secured user interface fronts. As a result, securing such servers is a relatively simple task because version control systems and issue trackers generally do not allow running arbitrary commands on the hosts running such servers. Unlike version control and issue tracking systems, build servers are inherently insecure because the main task of a build server is running arbitrary shell commands controlled by users, directly or by invoking scripting languages or tools such as Perl, make or ANT. Such commands perform file and network operations that alter the file system, and they also access various local and network resources as part of normal operations. Thus, build servers are inherently insecure. This is generally not a problem in a controlled or trusted environment of a software organization where the employees are usually not considered a security threat. Running a build server in uncontrolled or untrustworthy environments may present a serious security challenge. In the uncontrolled environment malicious users can easily modify build scripts in a version control system to perform tasks presenting various security threats ranging from access to sensitive data to the disclosure of security arrangements that might compromise the surrounding security infrastructure. Important Understand that build servers do run user-controlled shell commands and scripts. Do not run Viewtier Parabuild if one of these apply to you SCM infrastructure: 1. Your version control system allows anonymous write access to your project source line ; 2. Untrustworthy persons have write access to project your source line ; 3. There is no gate keeping process for anonymous or untrustworthy submissions and checkins. 18