Introduction

The pulse™ master server stores all persistent information in the data directory.This includes both configuration and build results. On the master and agents data directory is also used as a working area for builds in progress, and to hold working copies for incremental builds. This cookbook entry describes the layout and contents of the data directory.

Layout

Each subdirectory of the data directory is described in a subsection below.

agents

Used on both master and agents. Stores the working area under which agents run builds. As multiple agents may be run on a single host, each agent is given a separate directory. The layout is further divided into a temporary recipes area and a persistent work area:

• agents/
  • <agent name>/
    • recipes/
    • work/

recipes

A temporary working space for builds in progress on the pulse™ master and agents. Each stage will be executed in a subdirectory named for the recipe id. The contents of this subdirectory are temporary and it is removed at the end of the stage. The contents of this directory need never be backed up, and may be safely deleted when there are no builds in progress.

work

Stores a persistent work area used for projects that employ the "clean update" or "incremental update" checkout scheme. In the case of the former, source code is checked out to this area but is then copied into the temporary recipes/ area for building. In the case of the latter, the builds happen in place in this work area. The layout is something like:

• work/
  • <project name>/
    • (checked out source code)

The contents of this directory need not be backed up and may be safely deleted when no builds are in progress. In this case, a clean checkout will be used for the next build. Note that this directory can be quite large, especially when the "incremental update" scheme is used, as built binaries generally consume significant space.

archives

Stores export archives generated by pulse™. In particular, this directory contains the automatic configuration backups that pulse™ takes by default at 5am every morning. Master only.

backups

Stores automatically-created backups of your pulse™ embedded database, in zip archives named auto-backup-<version>.zip. When you upgrade pulse™, sometimes schema changes will be made to your existing database. In this case, if you are using the embedded database pulse™ will automatically take a backup of your database first.

External Databases If you are using an external database, you must back it up yourself before starting an upgrade.

These backups may be deleted once you are happy with the operation of your upgraded server. However, it is advisable to keep at least the most recent backup, and we would encourage you to use your own bacup mechanism external to pulse™ for maximum reliability. Master only.

config

On the pulse™ master, stores some server-level configuration information and customised user templates. This does not include the bulk of the configuration (e.g. projects, users), which is stored in records. Files and subdirectories include:

Agents also have a config directory, used to store just the service.token.

database

Stores the embedded database if in use. Note we do not recommend using the embedded database for production servers. Master only.

driver

Stores additional JDBC drivers if using an external database. Master only.

plugins

Stores all installed (including disabled) plugins and a registry file that maintains their state. Master and agents.

projects

Stores the build artifacts for each project on the master. This includes build logs, all captured artifacts and full test results. The layout is something like:

• projects/
  • <project id>/
    • <build number>/
      • pulse.xml
      • <recipe result id>/
        • base/ - the working copy for the stage, if retained
        • output/ - the artifacts and the full test results for the stage

The normal way to control the size of this directory is using cleanup rules. Note that capturing the working copy will often require a lot of space. This can be disabled for a project by ensuring the "retain working copy" option is not checked.

The contents of this directory are not essential for a minimal backup. Pulse can be restored without the full build data, although the logs, artifacts and full test results will be lost.

records

Stores the bulk of the server configuration information, including project and agent configuration, in XML files known as records. For durability and performance reasons the records are written incrementally as changed. However, snapshots are regularly taken of the whole configuration to the "snapshot" subdirectory. Editing this configuration by hand is not recommended and may lead to corruption. Master only.

users

This directory is analogous to the projects directory, but stores personal build results rather than project build results. The files stored are the same, with the addition of the patches uploaded by the user for personal builds in the users/<user id>/patches subdirectory.