Table of Contents
List of Examples
Table of Contents
This document provides the information you need to install and configure a Viewtier Parabuild server as a stand-alone server or as a remote builder.
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.
This guide is intended for anyone who is installing a Parabuild server or a remote builder 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.
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 www.viewtier.com .
650-240-4455
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.
Table of Contents
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.
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.
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.
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.6Mbor roughly 1Gb.
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 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
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.
Parabuild listens on port 8080. Certain applications and services such as Tomcat and Apache may also listen on port 8080. This may prevent Parabuild from starting up correctly. Make sure that no other services listen on port 8080.
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.
Table of Contents
For Windows, a single Parabuild setup program is available. In order to begin installation, type this command in the Windows command prompt:
parabuild_2_0_windows.exeThis 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.
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.
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:
Press the "Start" button;
Click on "Run" menu item;
Type "cmd" in the "Open" field, a command shell will open;
Type "net start parabuild". This command will start Parabuild service.
It is also possible to start Parabuild service using administrative interface:
Press the "Start" button;
Click on "Settings" menu item, Windows control panel will open;
Click on "Administrative Tools" icon;
Click on "Services" icon, Services management window will open;
Find Parabuild in the list of services, right click on it, select "Start". Parabuild service will start.
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:
Press the "Start" button;
Click on "Run" menu item;
Type "cmd" in the "Open" field, a command shell will open;
Type "net stop Parabuild". This command will stop Parabuild service.
It is also possible to stop Parabuild service using administrative interface:
Press the "Start" button;
Click on "Settings" menu item, Windows control panel will open;
Click on "Administrative Tools" icon;
Click on "Services" icon, Services management window will open;
Find Parabuild in the list of services, right click on it, select "Stop". Parabuild service will stop.
Some environments require manual actions to be taken after the installation of Parabuild is completed. Below you can find considerations for such environments.
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.
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.
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 your network. Please check section Changing Parabuild Service User for instructions.
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.
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:
Press the "Start" button;
Click on "Settings" menu item, Windows control panel will open;
Click on "Administrative Tools" icon;
Click on "Services" icon, Services management window will open;
Find Parabuild in the list of services, right click on it, select "Properties" menu item;
Select "Log On" tab;
Select "This account" radio button.
Enter a user name, an optional domain name and a password.
Press "OK" button.
Stop and start Parabuild service to activate the changes.
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.
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_2_0_linux.sh -qPlease 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.
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_2_0_linux.tar.gz -C /optTo complete installation, please proceed to the Post-installation Tasks chapter.
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_2_0_solaris.sh -qWhen installer finishes execution, Parabuild is installed in /opt/parabuild directory.
Table of Contents
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 1.4.2 is available on a machine that will run Parabuild.
If you are upgrading Parabuild, first stop Parabuild daemon and perform a full back up of the Parabuild installation directory.
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_2_0_mac_osx.sh -qPlease 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.
Parabuild is installed as a Mac OS X startup item. To start Parabuild daemon manually if it is not running follow the steps below:
Open Terminal.
Type sudo /Library/StartupItems/Parabuild/Parabuild start
Enter su's password
Parabuild daemon starts automatically when the Mac OS X system is re-started.
Table of Contents
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 1.4.2 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.
If you do not have Java SDK 1.4.2 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 .
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_2_0_generic_unix.sh -qWhen installer finishes execution, Parabuild is installed in /opt/parabuild directory.
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_HOMEIf 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_HOMETo complete the installation, please proceed to Unix Post-installation Tasks chapter.
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.
Normally Parabuild runs a few external process, so clearing them up may take few seconds.
Always stop the Parabuild server before upgrading. Performing an upgrade operation while the Parabuild server is running may render it unusable.
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.
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
http://build:8080/parabuild/admin/builds.htmA public build status page would be available for the members of your engineering team at the URL
http://build:8080/parabuild/index.htmThe default administrative password is "admin". Parabuild Administrator's Guide describes build administration in detail.
Table of Contents
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 builder mode, make sure you can telnet port 8080 on the XP machine from the build manager machine.
Parabuild can run in two modes: as a build manager mode or as remote builder. 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 builder mode.
In the build manager mode Parabuild:
Serves web user interface requests.
Maintains build archive
Runs local and remote builds
Sends build notifications.
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 builder, 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 builder mode.
Example 10.1. Fragment of parabuild.conf for Parabuild running in remote builder mode
parabuild.build.manager.ipaddress=192.168.123.2A build manager can run builds on multiple remote builders. A remote builder will serve as single build manager with the configured IP address only. The remote builder will accept requests coming from local addresses only, i.e. those starting with 192.168.*, 10.*, 172.16.*, 169.254.* and 127.0.0.1.
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.
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 .