BuildServerSetup

Build Server Setup

• Build Server Setup
  • Overview
  • Hardware
  • Operating System
  • Build Tools
    • Java SE JRE
    • Git
    • Nexus
      • Plugins
        • nexus-site-repository-plugin
        • unzip-repository-plugin
    • Jenkins
      • Tools
        • Java SE JDK
        • Ant
        • Maven
      • Plugins
        • Git
        • JaCoCo
        • Xvfb
  • The Build User
  • Build Scripts
  • Nexus
    • Create the Nexus Environment
    • Start Nexus
  • Jenkins

Overview

This article describes how to set up a Gamegineer build server. Details of the team's reference implementation are provided throughout the article to assist you in easily understanding the build server requirements.

At this time, the team only maintains a Linux build server reference implementation. The instructions in this article should be easily extendible to a Windows build server, but you may run into unforeseen issues not encountered on the Linux reference implementation. Please feel free to contribute instructions for setting up a Gamegineer build server on other platforms.

Hardware

It is preferable to have a dedicated machine as the build server. This will help you avoid corrupting your build environment with resources that exist outside of the version control repository. These external resources (e.g. different build tool versions, partially modified source code, etc.) have a tendency to make the build fail when it should pass and vice versa, resulting in much frustration.

However, physical hardware is not necessary. In fact, it is recommended you use a virtual machine to host your build server. Several free virtualization solutions are available, including:

• Oracle VirtualBox
• VMware Player
• Xen

The Linux reference implementation uses Oracle VirtualBox 4.3 with the following virtual hardware:

• Intel Core i5-3570K single-core CPU @ 3.4 GHz
• 1024 MB RAM
• 128 GB hard disk
• DVD-ROM drive
• Network adapter

Operating System

Install a clean operating system and all available updates on your chosen hardware. Install any required system software, such as an antivirus package. If you are using a VM, you should save this image before continuing.

The Linux reference implementation uses the following operating system and system software:

• CentOS 6.6 x86_64

Build Tools

Many of the build tools used by Gamegineer are not stored in version control simply due to the large size of their distributions. Therefore, it is necessary to install this software outside of the formal build process. As an administrative user, install the software packages that follow. Note that only specific versions have been approved for use on a Gamegineer build server; wildcards have been used where appropriate.

Java SE JRE

Install the latest update to version 1.7.0 of the Java SE 7 JRE. The Java SE 7 JRE is required to run Nexus.

The Linux reference implementation uses Oracle JRE 1.7.0_60 installed to /home/build/tools/jre1.7.0_60.

Git

Install version 1.7.9 or later of the Git client. A Git client is required to bootstrap the build server from the Gamegineer version control repository. It is also used by Jenkins to download the source for the various build jobs.

The Linux reference implementation uses the git RPM package version 1.7.12.4 from the rpmforge-extras repository installed to /usr/bin.

Nexus

Install version 2.6.x of Nexus. Nexus is used to manage build artifacts.

The installation package will contain two directories. For example, nexus-2.6.2-01 (hereafter referred to as nexus-home) and sonatype-work. The contents of nexus-home represent the actual application and should be copied to the appropriate installation directory (e.g. ~/tools/nexus-2.6.2-01). The contents of sonatype-work should be copied to ~/build-workspace/nexus (see below for the meaning of the ~/build-workspace/nexus directory).

You must edit the $nexus-home/conf/nexus.properties file, and change the value of the nexus-work property to the fully-qualified path to the ~/build-workspace/nexus directory.

To ensure Nexus does not fill up local storage with its artifacts, you must create several automated tasks that periodically remove old artifacts. Start Nexus and go to the Administration > Scheduled Tasks page. Create the following tasks:

• Remove Snapshots from Repository
• Purge Nexus Timeline
• Empty Trash

The Linux reference implementation uses Nexus OSS 2.6.2-01 installed to /home/build/tools/nexus-2.6.2-01.

Plugins

You must install the Nexus plugins listed below.

nexus-site-repository-plugin

Install version 2.6 or later of the Nexus site repository plugin. This plugin is used to host the project web sites generated using the Maven site goal. Refer to sections 18.5 and 18.6 of the Nexus book for installation instructions.

unzip-repository-plugin

Install version 0.12.0 or later of the Tycho Nexus unzip plugin. This plugin is used to publish zipped p2 update sites in a format the p2 director can consume. Refer to the Tycho/Nexus Unzip Plugin wiki for installation instructions.

Jenkins

Install the latest long-term support (LTS) version of Jenkins. Jenkins is the tool used to automate the build process.

The Linux reference implementation uses Jenkins LTS 1.596.2 installed using the RPM package.

Tools

You must configure Jenkins to use the following tools:

Java SE JDK

Add a JDK installation for Java SE Development Kit 7u51 to be installed automatically from java.sun.com.

Ant

Add an Ant installation for Ant 1.9.6 to be installed automatically from Apache.

Maven

Add a Maven installation for Maven 3.3.3 to be installed automatically from Apache.

Plugins

You must configure Jenkins to use the following plugins:

Git

Install Git plugin 2.4.0 or later. Configure it to use the Git client you installed above.

JaCoCo

Install JaCoCo plugin 2.0.0 or later.

Xvfb

Install Xvfb plugin 1.0.16 or later. Xvfb is used to provide a virtual display on this headless server because some tests exercise the GUI. The plugin does not automatically install Xvfb itself. Therefore, If necessary, install Xvfb on the server prior to installing the plugin.

The Build User

Create a dedicated, non-administrative user for hosting the build process. In the build user's home directory, create the following subdirectories:

• build-workspace
• scripts

The purpose of these directories will be discussed below.

The Linux reference implementation uses a user named build. The user's home directory is logically located at /home/build.

Build Scripts

Several scripts are used to drive the build process. These scripts depend on your specific build environment and thus cannot be provided in a generalized form. The build team provides templates for these scripts in the version control repository. You must download these templates to your build server the first time you set it up. As the Build User, follow these steps to download the templates (~ refers to the build user's home directory):

1. Use the Git client to clone the repository that contains the build file templates: git clone --depth=1 git://github.com/gamegineer/build.git ~/build-workspace
2. Copy all the script templates in ~/build-workspace/scripts to ~/scripts.

Now you must edit each of the script templates you copied. Using a text editor, open each of the script templates and supply appropriate values for the environment variables between the BEGIN-CUSTOM-VARIABLES and END-CUSTOM-VARIABLES markers.

If you are using a VM, you should save this image before continuing.

The Linux reference implementation uses the directory names defined in the templates.

Nexus

Create the Nexus Environment

The Nexus environment must be created every time the Build User logs in to the build server. This is accomplished by sourcing the ~/scripts/nexus-environment.sh script from a command window. This command window will become the focus of the Gamegineer Nexus environment. This script sets up all environment variables required by Nexus, as well as several other tasks documented in the script.

Start Nexus

At this point, you are ready to execute Nexus. From the Nexus environment command window you opened in the previous step, run the following command:

nexus start

Nexus is now running.

Alternatively, you can execute:

~/scripts/nexus-start

to run Nexus as a background process. Note that the nexus-start script performs the steps from the Create the Nexus Environment section above, so it is unnecessary to source the nexus-environment.sh script before executing nexus-start. Similarly, to stop a running Nexus process, you can execute

~/scripts/nexus-stop

Jenkins

It is recommended to install Jenkins using the RPM package. This will configure Jenkins to automatically start when the server is started.

The latest job configurations are stored in version control and can be found at ~/build-workspace/jenkins/jobs.