Skip to content

README.rst

Latest commit

 

History

History
224 lines (156 loc) · 6.57 KB

README.rst

File metadata and controls

224 lines (156 loc) · 6.57 KB

puppet-homebrew

A Puppet Module to install Homebrew and manage Homebrew packages on Mac OSX. This module can install using either homebrew or brewcask, along with a fallback mode which attempts both.

This module supports Puppet version 8 and greater running on Ruby v3.x (>=3.2). puppet-homebrew is available on the Puppet Forge.

Warning

As of v2+ of this project, development is AI-assisted.

Usage

Installing Packages

Use the Homebrew package provider like this:

class hightower::packages {
  pkglist = ['postgresql', 'nginx', 'git', 'tmux']

  package { $pkglist:
    ensure   => present,
    provider => brew,
  }
}

The providers works as follows:

  • provider => brew: install using brew install <module>. Do not use brewcask.
  • provider => brewcask: install using brew cask install <module>. Only use brewcask.
  • provider => homebrew: attempt to install using brew install <module>. On failure, use brew cask install <module>

Tapping Repositories

To tap into new Github repositories, simply use the tap provider:

package { 'neovim/neovim':
  ensure   => present,
  provider => tap,
}

You can untap a repository by setting ensure to absent.

Ordering Taps

When both tapping a repo and installing a package from that repository, it is important to make sure the former happens first. This can be accomplished in a few different ways: either by doing so on a per-package basis:

package { 'neovim/neovim':
  ensure   => present,
  provider => tap,
} ->
package { 'neovim':
  ensure   => present,
  provider => homebrew,
}

or by setting all taps to occur before all other usages of this package with Resource Collectors:

# pick whichever provider(s) are relevant
Package <| provider == tap |> -> Package <| provider == homebrew |>
Package <| provider == tap |> -> Package <| provider == brew |>
Package <| provider == tap |> -> Package <| provider == brewcask |>

Installing Brew

To install homebrew on a node (with a compiler already present!):

class { 'homebrew':
  user      => 'hightower',
  group     => 'developers',  # defaults to 'admin'
  multiuser => false,         # set to true to enable multiuser support for homebrew
}

Installing homebrew as the root user is no longer supported (as of late 2016). The homebrew::user must always be a non-root user (generally, the system's main user account).

This module supports two configurations:

  1. Puppet running as root (recommended): Set homebrew::user to the desired non-root user. Puppet will use su to run the homebrew installer and will manage directory ownership and permissions on behalf of that user.
  2. Puppet running as the homebrew user: Set homebrew::user to the same user that is running puppet. Puppet will run the homebrew installer directly and skip directory ownership management (the homebrew installer handles this itself).

Warning

Running puppet as non-root user X with homebrew::user set to a different user Y is unsupported and will produce an explicit error. Either run puppet as root or as the homebrew user directly.

If you are looking for a multi-user installation, please be sure to set the multi-user flag, eg.:

class { 'homebrew':
  user      => 'kevin',
  group     => 'all-users',
  multiuser => true,
}

If no compiler is detected, this module will automatically install the Xcode Command Line Tools via softwareupdate. No additional configuration is required:

class { 'homebrew':
  user => 'kevin',
}

Alternatively, you can install the Command Line Tools from a DMG by providing both a package name and source URL:

class { 'homebrew':
  user                       => 'kevin',
  command_line_tools_package => 'command_line_tools_for_xcode_os_x_lion_april_2013.dmg',
  command_line_tools_source  => 'http://devimages.apple.com/downloads/xcode/command_line_tools_for_xcode_os_x_lion_april_2013.dmg',
}

Adding a Github Token

Homebrew uses a Github token in your environment to make your experience better by:

  • Reducing the rate limit on brew search commands
  • Letting you tap your private repositories
  • Allowing you to upload Gists of brew installation errors

To enable this feature, you can include:

class { 'homebrew':
  user         => 'kevin',
  github_token => 'MyT0k3n!',
}

Here's a link to create a personal access token for Github.

Installing Casks with Elevated Permission Requirements

Sometimes, casks require elevated permissions at installation time. Handling the proper elevated permissions is currently out of scope of this module, but if you trust your homebrew operations enough you can grant your puppet user permissions to use sudo without requiring your password by adding the relevant lines in /etc/sudoers.d/homebrew or similar, along the lines of the following:

puppet ALL=(root) NOPASSWD:SETENV: /usr/bin/env

See #116 for more information.

Development

This repository uses rbenv for local Ruby version management. If rbenv is installed, ./bin/build uses the rbenv local Ruby version from .ruby-version. If rbenv is not available (for example in CI), it uses the current ruby on PATH.

Ruby 4.x is intentionally unsupported because current Puppet 8 dependencies are not compatible with Ruby 4.x.

Run the build and validation steps:

./bin/build

Optionally, provide a Puppet requirement constraint:

./bin/build --puppet '>=8.0.0'

Original Author

Original credit for this module goes to kelseyhightower. This module was forked to provide brewcask integration.

Credit for logic involved in tapping repositories goes to gildas.