docs/GettingStarted

@title Getting Started Guide

pfm Executable

Bundled with this gem is an executable pfm. The pfm executable is a command-line tool that does the following:

  • Generates server build repositories, templates, and default cookbooks
  • Builds images with Packer from existing server build repositories
  • Validates server build repositories, templates, and cookbooks

The following commands are available in PFM 0.3.x (see pfm -h for a full list):

Usage:
    pfm -h/--help
    pfm -v/--version
    pfm command [arguments...] [options...]


Available Commands:
    generate   Generate a new server build, repository, cookbooks, etc.
    build      Build a specified server template
    validate   Test & validate a server build
    exec       Runs the command in context of the embedded ruby
    configure  Run initial setup and configuration
    plan       Show the infrastructure plan
    apply      Apply the infrastructure plan
    destroy    Destroy all managed infrastructure
    format     format infrastructure code

Configuring pfm

.pfm/ Options Directory

The pfm executable will automatically generate a default config file located at .pfm/config. It will set sensible defaults, that should work for most implementations. You can change these settings by editing the file directly or running pfm configure.

See available settings in {Pfm::Settings}

pfm Commands

pfm generate server-build

Use the pfm generate server-build subcommand to generate server build repositories/templates.

Syntax
$ pfm generate server-build NAME [options]
Options

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output from the generator

-v, --version

  • Show pfm version
Examples

To generate a server build repositories, run a command similar to:

$ pfm generate server-build app-axpwa

pfm build

Use the pfm build subcommand to build server images (using Packer) from existing build repositories & templates (previously generated from pfm generate)

Syntax
$ pfm build BUILD_NAME [options]
Options

This subcommand has the following options:

-a VERSION, --app-release VERSION

  • Application Version Number to build

-n, --build-number NUMBER

  • Override the build number. Default is ENV::BUILD_NUMBER

-t, --build-template TEMPLATE

  • The Packer Build Template to use. The default template file is build.json. This file should reside in the root of the server build directory.

-m, --build-metadata METADATA_FILE

  • The build metadata file to use. The default metadata file is metadata. This file should reside in the root of the server build directory.

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output from the generator

-v, --version

  • Show pfm version
Examples

To build a server repositories/template, run a command similar to:

$ pfm build app-axpwa -a 3.1.0.1585

pfm validate server-build

Use the pfm validate server-build subcommand to validate a server build repository. This will run various tools such as Foodcritic, Rubocop, and ChefSpec against the build repo. Reports & Artifacts are generated and stored in .pfm/tests/{reports,artifacts}

Syntax
$ pfm validate server-build BUILD_NAME [options]
Options

-t, --build-template TEMPLATE

  • The Build Template to use. Default is build.json

-m, --build-metadata METADATA_FILE

  • The build metadata file to use. The default metadata file is metadata. This file should reside in the root of the server build directory.

-c, --circle-ci

  • Use Circle Ci artifact output directories

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output from the generator

-v, --version

  • Show pfm version
Examples

To validate a build repository, run a command similar to:

$ pfm validate server-build app-axpwa

pfm validate infrastructure

Use the pfm validate infrastructure subcommand to validate a server build repository. This will run various tools such as Foodcritic, Rubocop, and ChefSpec against the build repo. Reports & Artifacts are generated and stored in .pfm/tests/{reports,artifacts}

Syntax
$ pfm validate infrastructure [options]
Options

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output from the generator

-v, --version

  • Show pfm version
Examples

To validate a build repository, run a command similar to:

$ pfm validate infrastructure

pfm exec

Use the pfm exec subcommand to run arbitrary shell commands with the PATH environment variable and the GEM_HOME and GEM_PATH Ruby environment variables pointed at the Pfm bundle.

Syntax
$ pfm exec SYSTEM_COMMAND [options]
Options

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output from the generator

-v, --version

  • Show pfm version
Examples

None.

pfm plan

Use the pfm plan subcommand to plan infrastructure changes before they are executed.

Syntax
$ pfm plan [options]
Options

-a, --app-release VERSION

  • Application Version Number to Deploy

-b, --server-build BUILD_NUMBER

  • The build number of the AMI to deploy

-l, --landscape

  • Format the Terraform plan output with terraform_landscape

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output

-v, --version

  • Show pfm version
Examples

To plan an infrastructure release with application version number 3.1.0.1654, run a command similar to:

$ pfm plan -a 3.1.0.1654

pfm apply

Use the pfm apply subcommand to apply infrastructure changes before they are executed.

Syntax
$ pfm apply [options]
Options

-a, --app-release VERSION

  • Application Version Number to Deploy

-b, --server-build BUILD_NUMBER

  • The build number of the AMI to deploy

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output

-v, --version

  • Show pfm version
Examples

To apply an infrastructure release with application version number 3.1.0.1654, run a command similar to:

$ pfm apply -a 3.1.0.1654

pfm destroy

Use the pfm destroy subcommand to destroy a managed environment and all associated resources. THIS CANNOT BE UNDONE

Syntax
$ pfm destroy [options]
Options

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output

-v, --version

  • Show pfm version
Examples

To destroy a managed environment

$ pfm destroy

pfm format

Use the pfm format subcommand to format an infrastructure repository and associated files to a canonical format.

Syntax
$ pfm format [options]
Options

-h, --help

  • Show this message

-V, --verbose

  • Show detailed output

-v, --version

  • Show pfm version
Examples

To format an infrastructure repository’s files

$ pfm format