| | h2. Overview |
| | |
| | This guide provides quick-start instructions for installing a {pn} 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. |
| | |
| | h2. Upgrading |
| | |
| | If you are upgrading from a previous version of {pn}, the setup procedure depends on the version you are coming from: |
| | |
| | h3. 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|pulse0102:Migrating from 1.2.x to 2.0] for details on upgrading. |
| | | 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|pulse0200:Migrating from 1.2.x to 2.0] for details on upgrading. |
| | |
| | h3. 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 {pn} has been shut down, and you have backed up all data. When you reach the step asking you for the {pn} data directory, simply enter the path to the data for your current {pn} 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 {pn} will start up and you will be able to start using it immediately. Refer to the [Upgrading] page for more details. |
| | |
| | h2. Installation and Setup |
| | |
| | h3. Requirements |
| | |
| | {pn} has just two prerequisites: |
| | |
| | * A Java Runtime Environment (JRE), version 1.5 or higher. [Sun Microsystems|http://sun.com/] distribute a suitable JRE, available at [http://java.sun.com/j2se/1.5.0/download.jsp]. Ensure that you set up the environment variable {{JAVA_HOME}} and add the {{java}} binary to your {{PATH}} during the setup procedure. |
| | * *(Perforce users only*) The [Perforce|http://perforce.com/] command-line client {{p4}}. The client is available for a wide variety of platforms at [http://perforce.com/perforce/loadprog.html]. |
| | |
| | {note}Ensure that the {{p4}} binary is in the {{PATH}} of the {pn} process (perhaps by adding it to the system {{PATH}}).{note} |
| | |
| | {note}{pn} personal builds requires perforce version 2004.2 or later{note} |
| | |
| | h3. Obtaining Packages |
| | |
 | | {pn} packages are currently available from the [Early Access Program] page. Packages have names of the form: |
| | | {pn} packages are available from the [zutubi website|http://zutubi.com/] 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 {pn} contained in the package, e.g. "1.0". |
| | |
| | h3. Obtaining Licenses |
| | |
| | If you have not already obtained a license, you can request an evaluation license directly within the {pn} setup wizard. The license will also be emailed to an address you specify. If the server that you are installing {pn} on is not connected to the internet, you can also apply to have a licensed emailed to you at the [zutubi website|http://www.zutubi.com/sales/evaluation/]. Evaluation licenses allow you to try a fully-functional version of {pn} for 30 days. |
| | |
| | h3. Installation |
| | |
| | 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|Getting Started Guide#Setup]). |
| | |
| | A {pn} 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: |
| | |
| | {noformat} |
| | $ cd /usr/local |
| | $ ls |
| | pulse-2.0.tgz |
| | $ tar zxf pulse-2.0.tgz |
| | $ ls |
| | pulse-2.0 pulse-2.0.tgz |
| | $ |
| | {noformat} |
| | |
| | The directory the archive is unpacked into is known as the {pn} home directory. To be able to run {pn} 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): |
| | |
| | {noformat} |
| | $ export PULSE_HOME=/usr/local/pulse-2.0 |
| | {noformat} |
| | |
| | To ensure this variable is always set, edit your profile or shell rc file, or use the Windows Control Panel. |
| | |
| | |
| | h3. Setup |
| | |
| | The {pn} server is controlled from a single script named {{pulse}} ({{pulse.bat}} for Windows users) located in the {{bin}} directory. You can start your {pn} server by running the {{pulse}} script with the command {{start}}: |
| | |
| | {noformat} |
| | $ cd pulse-2.0 |
| | $ ./bin/pulse start |
| | Now go to http://localhost:8080/ and follow the prompts. |
| | {noformat} |
| | |
| | After a few moments, {pn} 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. |
| | |
| | h3. Shutting Down |
| | |
| | To gracefully shut down your {pn} server, use the {{pulse}} script with the {{shutdown}} command: |
| | |
| | {noformat} |
| | $ ./bin/pulse shutdown |
| | {noformat} |
| | |
| | You may find it more convenient to run your {pn} server as a service, by installing appropriate init scripts (on Unix-like systems), or by starting as a Windows service. |
| | |
| | h2. Adding a Project |
| | |
| | h3. 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 {pn} 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|Pulse File Projects], then you will also need to create a {pn} file for your project. If it is a [versioned project|Versioned Projects] you will need to check the file in to your SCM. |
| | |
| | h3. 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 {pn} 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|Triggers], 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 {pn} 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. |
| | |
| | h2. Where To Next |
| | |
| | The main source of further information is the [pulse manual|Manual]. You can access content-sensitive help from the {pn} web interface by clicking on the help link in the top right hand corner of the page. |
| | |
| | h3. Common Next Steps |
| | |
| | h4. Learning More |
| | |
| | We encourage you to read the [Introduction] in the {pn} [Manual], and in particular the pages [Understanding Builds] and [Understanding Templates]. |
| | |
| | h4. Running as a Service |
| | |
| | It is usually most convenient to install {pn} as a service. For details, see the [Running as a Service] page. |
| | |
| | h4. Securing {pn} |
| | |
| | For security reasons, you should run your {pn} server in a sandbox. The easiest way to achieve this is to run the {pn} process as a regular user with limited privileges. See the [Running as a Service] page for details on controlling the user that executes {pn}. |
| | |
| | h4. Installing Agents |
| | |
| | To take advantage of the distributed building capabilities of {pn}, you must install agent servers. See the [Agents] section for details. |
| | |
| | h4. Installing Developer Tools |
| | |
| | Advanced {pn} features such as [Personal Builds] require installation of tools on your development machines. See the [Developer Tools Manual] for more information. |
