This guide provides quick-start instructions for installing a pulse™ server. It covers the minimal steps required to install the server and get a single project building. Further information can be found in the Manual, which is linked to in various places throughout this document.
For the Impatient
Fair enough: we don't like reading instructions either! The fast path to installation is as follows:
- Install Java 1.6 or later (if you haven't already).
- Download a pulse™ package from zutubi.com.
- Run the pulse™ installer (Windows) or unpack the archive (any OS).
- Start the pulse™ service (Windows) or run "<install directory>/bin/pulse start" (any OS).
- Point your browser at http://localhost:8080/ and follow the prompts.
Further details are included below. Assuming the above steps go well, skip to the end of this document for suggested next steps.
If you are upgrading from a previous version of pulse™, the setup procedure depends on the version you are coming from:
Upgrading From 1.2.x
Dues to major changes between the 1.2 and 2.x release streams, upgrading from 1.2 uses a custom tool with its own instructions. Please see Migrating from 1.2.x to 2.x for details on upgrading.
Upgrading From 2.x
Due to changes to unversioned components, users upgrading from an earlier pulse™ 2.x release should first ensure they have upgraded to version 2.6.20 or later before upgrading to 2.7.x. This ensures automatic agent upgrades will work up to the 2.7.x version. If you are on 2.6.19 or earlier, first upgrade to the latest 2.6.x version, then on to the latest 2.7.x version.
The process for upgrading is the same as below. Make sure the previous version of pulse™ has been shut down, and you have backed up all data. When you reach the step asking you for the pulse™ data directory, simply enter the path to the data for your current pulse™ installation. Pulse will recognise the data, inform you of any upgrade tasks required, and perform the upgrade automatically. When the upgrade has completed, the new version of pulse™ will start up and you will be able to start using it immediately. Refer to the Upgrading page for more details.
You may want to check the Compatibility Notes before upgrading to see if there are any changes that concern you.
Installation and Setup
pulse™ has just one primary prerequisite:
- A Java Runtime Environment (JRE), version 1.6 or higher. Oracle distribute a suitable JRE, available at http://www.oracle.com/technetwork/java/javase/downloads/index.html. Ensure that you set up the environment variable
JAVA_HOMEand add the
javabinary to your
PATHduring the setup procedure.
Note that support for certain SCMs requires the native client to be installed and in the
PATH of pulse™:
- Perforce Support: The Perforce command-line client
p4. The client is available for a wide variety of platforms at http://perforce.com/perforce/loadprog.html. Note that personal builds require version 2004.2 or later.
- Git Support: The
gitcommand-line client. Available from http://git-scm.com/.
- Mercurial Support: The
hgcommand-line client. Available from http://mercurial.selenic.com/.
pulse™ packages are available from the pulse™ downloads page. Packages have names of the form:
pulse-<version>.tgz (compressed tar archives)
pulse-<version>.zip (ZIP archives)
pulse-<version>.exe (Windows installers)
Where <version> is the version of pulse™ contained in the package, e.g. "2.7.0".
If you have not already obtained a license, you can request an evaluation license directly within the pulse™ setup wizard. The license will also be emailed to an address you specify. If the server that you are installing pulse™ on is not connected to the internet, you can also apply to have a licensed emailed to you at the zutubi website. Evaluation licenses allow you to try a fully-functional version of pulse™ for 30 days.
The package installation processes differs depending on whether you have downloaded a Windows installer or an archive (tarball/zip). For those using the Windows installer, simply run the installer and follow the prompts. When the installer completes, continue at the next step (Setup).
A pulse™ archive may be installed anywhere on the host system by unpacking the archive. The archive unpacks into a directory of the same name as the archive file, excepting the extension. For example:
The directory the archive is unpacked into is known as the pulse™ home directory. To be able to run pulse™ scripts from outside of this directory, you must set the value of
PULSE_HOME to the absolute path of the directory, for example (assuming a bash-like shell):
To ensure this variable is always set, edit your profile or shell rc file, or use the Windows Control Panel.
The pulse™ server is controlled from a single script named
pulse.bat for Windows users) located in the
bin directory. You can start your pulse™ server by running the
pulse script with the command
After a few moments, pulse™ will display a message similar to the above. You can now open http://localhost:8080/ in a web browser running on the host machine (or
http://<host>:8080/ from another machine) to complete the setup wizard.
To gracefully shut down your pulse™ server, use the
pulse script with the
You may find it more convenient to run your pulse™ server as a service, by installing appropriate init scripts (on Unix-like systems), or by starting as a Windows service.
Adding a Project
Add Project Wizard
After completing the setup wizard, you will be logged in as the administration user and presented with a Welcome page. This page provides helpful links for configuring and exploring your new pulse™ server. To add a new project, click the "add new projects" link which will take you to the projects area in the administration section. Here you can click the "add new" link to start the add project wizard. This wizard will guide you through the steps for adding a project:
- Step 1: Basic project details.
- Step 2: SCM type: select the type of SCM that contains your project source.
- Step 3: SCM details for the project source code.
- Step 4: Project type: for simple projects, choose "single-step project" and the type of command to run. Projects requiring greater flexibility can use multiple steps, or even a hand-written pulse file.
- Step 5: Type-specific details (e.g. Makefile and targets)
If you choose to create a multi-step project you will next need to configure the steps by going to the project's configuration and adding a recipe. Alternatively, if you choose to create a pulse file project, then you will also need to create a pulse™ file for your project. If it is a versioned project you will need to check the file in to your SCM.
Your First Build
When the wizard completes, you will be taken to the hierarchy page for your new project. You can switch to the configuration details by selecting the "configuration" tab at the bottom of the tree view, or by clicking the "configure" link in the right-hand pane. This page allows you to edit all settings for the project. You should see that pulse™ has filled in some areas with sensible defaults that allow you to get started quickly. The project will also be configured with a single SCM monitoring trigger, which will trigger a build of the project whenever a change is detected to the project source code.
When you are happy with the project configuration, you can switch to the reporting side of the pulse™ UI by clicking on the "browse" link in the top navigation bar. You should see your new project listed in the "projects" table. You can manually trigger the first build of your project by clicking on down arrow button beside the project name and selecting "trigger" from the displayed menu. After a few moments the build will commence and you will be able to track its progress via the browse, project home page and build tabs.
Where To Next
The main source of further information is the pulse manual. You can access content-sensitive help from the pulse™ web interface by clicking on the help link in the top right hand corner of the page.
Common Next Steps
Running as a Service
It is usually most convenient to install pulse™ as a service. For details, see the Running as a Service page.
For security reasons, you should run your pulse™ server in a sandbox. The easiest way to achieve this is to run the pulse™ process as a regular user with limited privileges. See the Running as a Service page for details on controlling the user that executes pulse™.
To take advantage of the distributed building capabilities of pulse™, you must install agent servers. See the Agents section for details.