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.
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.0 release streams, upgrading from 1.2 uses a custom tool with its own instructions. Please see Migrating from 1.2.x to 2.0 for details on upgrading.
Upgrading From 2.0.x
When upgrading from an earlier 2.0.x build, most of the setup procedure 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.
Installation and Setup
pulse™ has just two prerequisites:
|Ensure that the p4 binary is in the PATH of the pulse™ process (perhaps by adding it to the system PATH).|
|pulse™ personal builds requires perforce version 2004.2 or later|
pulse™ packages are available from the zutubi website 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. "1.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:
$ cd /usr/local
$ tar zxf pulse-2.0.tgz
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):
$ export PULSE_HOME=/usr/local/pulse-2.0
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 (pulse.bat for Windows users) located in the bin directory. You can start your pulse™ server by running the pulse script with the command start:
$ cd pulse-2.0
$ ./bin/pulse start
Now go to http://localhost:8080/ and follow the prompts.
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 shutdown command:
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: SCMs details for the project source code.
- Step 4: Project type: select a built-in type or custom for more flexibility.
- Step 5: Type-specific details (e.g. Makefile and targets)
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 the lightning link in the project row. After clicking the link you will be taken to the project's home page, where you will be able to watch the build in progress.
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
We encourage you to read the Introduction in the pulse™ Manual, and in particular the pages Understanding Builds and Understanding Templates.
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.
Installing Developer Tools
Advanced pulse™ features such as Personal Builds require installation of tools on your development machines. See the Developer Tools Manual for more information.