# perforce

#### Table of Contents
1. [Module Description - What the module does and why it is useful](#module-description)
1. [Setup - The basics of getting started with Perforce](#setup)
  * [Common Attributes - ](#common-attributes)
  * [Perforce Client (p4) - command-line client used to interact with a Perforce service](#perforce-client)
  * [Perforce Server (p4d) - the main Perforce service](#perforce-server)
  * [Perforce Broker (p4broker) - the Perforce broker component](#perforce-broker)
1. [Server Deployment Package - managing the SDP with Puppet](#server-deployment-package)
  * [Managing Instances - managing service (p4d and p4broker) instances](#managing-instances)

## Module Description

The Perforce module installs, configures, and manages the various Perforce components.

> NOTE: This module is currently under development. I thought I'd release it to the forge as it's
> progressed pretty well, but there are still several things that are being modified.
>
> Specifically:
> * Documentation -- docs are a work in progress (aren't they always??)
> * Tests -- basic unit tests are in the `examples` directory, but rspec tests are still forthcoming
> * Windows Support -- still needs some work so right now it's not enabled
> * Other Product Support -- later I want to expand this to Proxy (p4p), P4Web, etc. support but
> initially I am focussed on p4, p4d, and p4broker

This is the perforce module. It provides the ability to manage Perforce client
and server components, within an SDP (Server Deployment Package) environment.

## Setup

### Getting Started with Perforce

#### Common attributes

The client, server and broker classes support the following common attributes:

| attribute            | description |
| -------------------- | ----------- |
| source_location_base | Base location for the source. Defaults to the standard Perforce distribution site: `ftp://ftp.perforce.com/perforce`. This can be hosted locally, using the following protocols: `http(s)`, `puppet`, `ftp`, or `local` (used for network mounts) |
| dist_dir_base        | Distribution directory base -- used as part of the source path (after the r*version_number* directory). This value is calculated based on the OS and architecture. |
| staging_base_path    | The location where the binaries will be staged on the local node's filesystem. This defaults to `/var/staging/perforce`. |
| install_dir          | The location where the binaries will be installed |
| refresh_staged_file  | a boolean indicating whether the staged file should be refreshed. Defaults to `false`. The implication of this is that new versions will not be downloaded as long as the staged file is present, so upgrades need to have this value (temporarily) set to `true`. This value could be left as `true` if the source_location_base is some local system. |

For example, on 64-bit Linux, the default location for the p4d binary would be
`ftp://ftp.perforce.com/perforce/r15.1/bin.linux26x86_64/p4d`

#### Perforce Client

##### Usage

If you want the Perforce command-line client (p4) managed with the default options you can declare

`include '::perforce::client'`

If you need to customize options, such as the p4 version to manage or the install location, you can pass in the attributes:

~~~
class { '::perforce::client':
  p4_version    => '2015.1',
  install_dir   => '/usr/local/bin',
}
~~~

When installing in an SDP (Server Deployment Package) environment, ensure that the `perforce::sdp_base` class is declared. If declared, then the client software will be installed in the /p4/common/bin directory and the associated version and symbolic links will be created. When installing in an SDP environment, do not specify the install_dir attribute, as the install location should be controlled by the SDP installation.

~~~
include ::perforce::sdp_base
include ::perforce::client
~~~

##### Attributes

In addition to the common attributes, the following attributes are available with the `perforce::client` class:

| attribute  | description |
| ---------- | ----------- |
| p4_version | The version of the p4 client to manage. Defaults to `2015.1`. |


#### Perforce Server

> NOTE: This class is used to manage the p4d binaries on the node, but it does not manage an instance.
> Instances can be managed using the defined type `perforce::instance`, but this type does require
> that the SDP is also being managed.

##### Usage

If you want the Perforce service (p4d) managed with the default options you can declare

`include '::perforce::server'`

If you need to customize options, such as the p4d version to manage or the install location, you can pass in the attributes:

~~~
class { '::perforce::server':
  p4d_version   => '2015.1',
  install_dir   => '/usr/local/bin',
}
~~~

When installing in an SDP (Server Deployment Package) environment, ensure that the `perforce::sdp_base` class is declared. If declared, then the software will be installed in the /p4/common/bin directory and the associated version and symbolic links will be created. When installing in an SDP environment, do not specify the install_dir attribute, as the install location should be controlled by the SDP installation.

The SDP requires that a Perforce client also be present, so typically the `perforce::client` class should also be declared

~~~
include ::perforce::sdp_base
include ::perforce::client
include ::perforce::server
~~~

##### Attributes

In addition to the common attributes, the following attributes are available with the `perforce::server` class:

| attribute  | description |
| ---------- | ----------- |
| p4d_version | The version of the p4 client to manage. Defaults to `2015.1`. |


#### Perforce Broker

> NOTE: This class is used to manage the p4broker binaries on the node, but it does not manage an instance.
> Instances can be managed using the defined type `perforce::instance`, but this type does require
> that the SDP is also being managed.

##### Usage

If you want the Perforce broker service (p4broker) managed with the default options you can declare

`include '::perforce::broker'`

If you need to customize options, such as the p4broker version to manage or the install location, you can pass in the attributes:

~~~
class { '::perforce::broker':
  p4broker_version => '2015.1',
  install_dir      => '/usr/local/bin',
}
~~~

When installing in an SDP (Server Deployment Package) environment, ensure that the `perforce::sdp_base` class is declared. If declared, then the software will be installed in the /p4/common/bin directory and the associated version and symbolic links will be created. When installing in an SDP environment, do not specify the install_dir attribute, as the install location should be controlled by the SDP installation.

The SDP requires that a Perforce client also be present, so typically the `perforce::client` class should also be declared

~~~
include ::perforce::sdp_base
include ::perforce::client
include ::perforce::broker
~~~

##### Attributes

In addition to the common attributes, the following attributes are available with the `perforce::broker` class:

| attribute  | description |
| ---------- | ----------- |
| p4broker_version | The version of the p4 client to manage. Defaults to `2015.1`. |

### Server Deployment Package

The Perforce SDP provides a sample implementation of best practices, such as performing offline checkpoints, rotating logs and journals routinely, and doing a database sanity/safety check before starting the server. It is open source and available at [https://swarm.workshop.perforce.com/projects/perforce-software-sdp](https://swarm.workshop.perforce.com/projects/perforce-software-sdp)

#### SDP Commmon Files

##### Usage

The `perforce::sdp_base` class manages the base SDP installation. To declare this class and accept the default attribute values, you can use

`include '::perforce::sdp_base'`

If you need to customize options, such as the OS user to manage or the install location, you can pass in the attributes:

~~~
class { '::perforce::sdp_base':
  osuser => 'perforce',
  osgroup => 'perforce',
  p4_dir => '/p4',
}
~~~


##### Attributes

The following attributes can be used to configure how the SDP base installation is managed.

| attribute  | description |
| ---------- | ----------- |
| osuser            | Operating system user that will own the SDP directories and executables. This is managed within the class. Defaults to `perforce`. |
| osgroup           | Operating system group that will own the SDP directories and executables. This is managed within the class. Defaults to `perforce`. |
| adminuser         | Perforce admin user. Defaults to `p4admin`. This user will not be created in the Perforce server instance. |
| adminpass         | Password for the Perforce admin user. The value will be written to the adminpass file. Defaults to `undef`. |
| mail_to           | Email address to which administrative messages (e.g. daily backup script output) will be sent. Defaults to `p4admins`. |
| mail_from         | Email address used as the 'from' address in outgoing email messages. Defaults to `p4admin`. |
| p4_dir            | The base SDP directory. Defaults to `/p4` on Linux systems. |
| depotdata_dir     | The mountpoint for the Perforce depot data. This mountpoint must already exist (i.e. is managed outside the `perforce::sdp` class.). This defaults to `/depotdata` on Linux. |
| metadata_dir      | The mountpoint for the Perforce metadata. This mountpoint must already exist (i.e. is managed outside the `perforce::sdp` class.). This defaults to `/metadata` on Linux. |
| logs_dir          | The mountpoint for the Perforce and SDP log files. This mountpoint must already exist (i.e. is managed outside the `perforce::sdp` class.). This defaults to `/logs` on Linux. |
| sslprefix         | The default ssl prefix to use (e.g. `ssl:`). This defaults to `undef`. |
| sdp_version       | The SDP version to manage. This defaults to `Rev. SDP/MultiArch/2015.1/15810 (2015/09/21).` |
| staging_base_path | The location where the binaries will be staged on the local node's filesystem. This defaults to `/var/staging/perforce`. |



#### Managing Instances

##### Usage

Instances can only be managed within the context of an existing `perforce::sdp_base` installation. Managed instances can be server, broker, or both.

The `perforce::instance` defined type requires that

For example, to create a p4d instance called '1' with the server_id 'master', declare the following:

~~~
include ::perforce::sdp_base
include ::perforce::client
include ::perforce::server

::perforce::instance {'1':
  server_id    => 'master',
  ensure       => 'running',
  p4port       => '1666',
}
~~~

##### Attributes

###### common attributes
| attribute  | description |
| ---------- | ----------- |
| ensure     | The run setting for the managed services. Should be `running` or `stopped`. Default is `running`. |

###### p4d attributes
| attribute      | description |
| -------------- | ----------- |
| p4port         | If set, then a p4d instance is managed on the node. Default is `undef`. |
| server_id      | The server_id of the instance. A server_id file with the value of this attribute will be created in the root directory of the instance. Default is `$title` |
| is_master      | Flag to indicate whether this is a master or replica. Default is `true`. |
| master_dns     | The DNS name of the master server. This is needed if the instance is a replica. Default is `undef`. |
| ssl            | A boolean indicating whether or not ssl is required for the instance. Default is `false`. |
| case_sensitive | A boolean indicating whether or not the instance will run in case sensitive mode. Default is `false`. |
| p4d_version    | The version of p4d to use. Should be in the format *yyyy.n* (e.g. 2015.1). Default is `undef`. |

###### p4broker attributes
| attribute        | description |
| ---------------- | ----------- |
| p4brokerport     | If set, then a p4broker instance is managed on the node. Default is `undef`. |
| p4broker_version | The version of p4broker to use. Should be in the format *yyyy.n* (e.g. 2015.1). Default is `undef`. |
| p4broker_target  | The P4PORT of the instance with which the broker will communicate. Default is `undef`. |






.