Skip to content
This repository has been archived by the owner on Feb 26, 2020. It is now read-only.

Home

Jump to bottom
Lyza Gardner edited this page Nov 10, 2015 · 13 revisions

Cloud Four Boxen is a customized clone of GitHub's Boxen, providing a base development environment for Cloud Four staff. Boxen (and Boxen Web) are a set of tools that leverage Puppet to automate the installation of software on OS X machines. This is intended primarily for bootstrapping new Macs, though users are free to update/add software outside of the Boxen framework.

GitHub uses Boxen internally for provisioning, and employees are encouraged to modify and add to the configurations as toolsets evolve. See additional notes under Project manifests and Additional users below.

Provisioning Instructions

First Time:

  1. Start up a clean Mac and go through the default user setup process
  2. Turn on FileVault
  3. Open System Preferences
  4. Security & Privacy
  5. FileVault
  6. Unlock to make changes
  7. Turn on FileVault...
  8. Write down the recovery key; optionally store with Apple
  9. Restart. Note you do not need to wait for the disk encryption to complete.
  10. Install at least XCode command-line tools (xcode-select --install)
  11. Optional: prevent the computer from sleeping while plugged in (in the energy saver preference pane)
  12. Use Boxen-Web to provision the machine
  13. Open Safari
  14. Visit https://cloudfour-boxen.herokuapp.com/
  15. OAuth with a github user (Note: usernames with - may cause problems)
  16. Open a terminal
  17. Paste the command listed in Safari (under "Welcome to Boxen")
  18. Follow the prompts; get a cuppa; enter password for sudo; wait; etc.

Note: once successful, the script may prompt to source the boxen script in a .profile or similar (as below). However, this seems to be part of the script and should not be needed. Ed.: It's definitely not needed. Boxen is being a bit stupid here.

[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh

Pulling subsequent updates

Once /opt/boxen/repo contains a copy of the repository, updates can be performed at will:

cd /opt/boxen/repo
git pull origin master
# or: `git branch --set-upstream-to=origin/master master`
# one time only, then `git pull` for every pull/update
./script/boxen

This way people are free to add software (apps, gems, Node modules, etc.) and generally share improvements to the toolset with the team.

XCode Command-line Tools

Boxen requires XCode command-line tools to be installed and up-to-date. After OS upgrades, migrations, or if Boxen is not playing nice (manifested by messed-up ruby headers, missing gem files, etc. in error output), you should:

  • Open XCode (if installed). Click "OK" if and when prompted to download updates.
  • Run xcode-select --install in a terminal

Installation Notes

From the readme:

  • Boxen requires at least the Xcode Command Line Tools installed.
  • Boxen will not work with an existing rvm install.
  • Boxen may not play nice with a GitHub username that includes dash(-)
  • Boxen may not play nice with an existing rbenv install.
  • Boxen may not play nice with an existing chruby install.
  • Boxen may not play nice with an existing homebrew install.
  • Boxen may not play nice with an existing nvm install.
  • Boxen recommends installing the full Xcode.

The WalMart laptops appear to meet these requirements, and allow sudo access. Boxen provisioning should work as expected.

If you run into trouble running the boxen script (which is run by the shell script from Boxen Web), then try running with verbose logging: /opt/boxen/script/boxen --debug.

Troubleshooting

  • Make sure XCode command-line tools are up-to-date, and, if XCode is installed, all of its components are up to date.
  • Make sure there are no local changes in the boxen repo on the machine in question.
  • Make sure github user has been added to cloudfour team (and accepted the invite) and given access to the cloudfour-boxen repo thusly (symptom of failing this: boxen-web will 401).

Known Limitations

  • Slack is no longer supported as a puppet module; please install from the App Store.
  • No extant puppet scripts for Adobe CS suite.

Working with cloudfour-boxen

The Custom Boxen Config

There are a few files you may commonly edit:

  • Puppetfile is used by puppet-librarian to install dependencies (a la bundler).
  • manifests/site.pp is the main Puppetfile used to configure the box. It will always get used. We source this from upstream (our-boxen), so changes should be made to the cloud four module (see next bullet) or other sub-modules unless they must be made here.
  • modules/cloudfour/manifests/init.pp is our Cloud Four-specific set of things to install. This will also always get used for everyone.
  • hiera/common.yaml sets some common config values.

Adding something new to a module

The high-level steps are:

  1. Tell boxen via Librarian/Puppetfile to require the dependency (module) in question
  2. include the required module in the module you want to install it with (e.g. cloudfour company module, your personal module).
  3. Potentially add some config or other additional code to install the package in a particular way (depends on the specific module you're installing).

Theoretical Example: Add evernote to the cloudfour main company module using boxen's puppet-evernote. This process should work generally for any boxen puppet-* module.

  1. Use the github method to include the Evernote module in Puppetfile.
  2. Version numbers! Note that the version number in the Puppetfile corresponds to a tag in the github repo for the puppet-* module in question. It must match exactly; this isn't a dependency resolver. NB: The version is not the version of the software you're installing. It is a reference to a tag.
  3. To use the evernote module, add include evernote into the module you want to install it with. In our example case that would be modules/cloudfour/manifests/init.pp. Be sure to reference the README of whatever module you're installing for specific usage instructions.
  4. Running ./script/boxen will then download the new sources, adding a tarball to vendor/puppet/cache, and updating the Puppetfile.lock. See "Caching" below.

Our goal is to install the basics used by our devs & designers, while allowing plenty of room for custom additions and configuations. The default github manifest takes care of a lot of the basics.

See the Puppetfile (under "Optional/custom modules") for additions.

This may be easier to understand by looking at some of the modules in the repo directly.

Getting changes/updates from Github's boxen

Same as pulling in changes to any forked repo. Set our-boxen as upstream to the cloudfour-boxen repo and merge changes from there. More info.

We share most of our common stuff with github's boxen setup—we merge in their Puppetfile and manifests/site.pp via the upstream for this repo. That means we, by default, start with the set of things github has defined there. We build on top of that in our cloudfour module.

Why

To Provision employee OS X machines.

Boxen seems like a good fit for activity, community support, and extensibility (through Puppet).

Boxen installs binaries to opt/boxen (this is configurable), and in general tries to be as unobtrusive as possible. Note that installing services (e.g., PostgreSQL) will by default run on non-standard ports. Boxen uses Puppet, but most of what we need is supported out of the box. If custom Puppet modules are needed, it's pretty easy to learn (a Ruby DSL).

Alternatives considered:

Boxen Web

boxen-web makes it easier to provision new laptops with our boxen setup; it allows the .

Our deployed version of the standard github app is at cloudfour-boxen.herokuapp.com.

This is not to be confused with the GitHub repo, which contains the custom Boxen config.

Caching

The vendor directory contains downloaded tarballs from your sources (namely, github). TODO: You may check these files into git, or have git ignore them. Github recommends checking those files in for speed, but there's some discussion at issue 48.

Future changes (TODO)

Additional users

Users can have their own custom modules

Note that users can also have their own configurations specified at hiera/users/{github_login}.yaml

Project manifests

Project manifests allow custom configs for easy setup of a specific project (e.g., start running a local server immediately). Useful for any projects with ongoing long-term development.

DNS CNAME

Something like https://setup.cloudfour.com -> https://cloudfour-boxen.herokuapp.com

Clone this wiki locally