norm / suited

Set up your macOS development environment

suited

Set up your Mac OS X development environment as a lone developer, or as part of a team.

Quick example usage and suitfile

From a fresh install of macOS/OS X, create an account that can administer the computer.

Open the Terminal application and setup some environment variables.

export GIT_NAME='Wendy Testaburger'
export GIT_EMAIL='[email protected]'
export GITHUB_USER='wendy'

Create a new GitHub personal access token with at least the repo and write:public_key scopes active. Copy the token into your environment.

export GITHUB_TOKEN='123abc...'

Create a new SSH key and register it with GitHub (or copy an existing one you already have to your computer).

# create key and add to the ssh-agent
ssh-keygen -trsa -b4096 -C "$GIT_EMAIL" -f $HOME/.ssh/id_rsa
ssh-add $HOME/.ssh/id_rsa

# upload new key to GitHub
pubkey=$( cat $HOME/.ssh/id_rsa.pub )
json=$( printf '{"title": "%s", "key": "%s"}' "$GIT_EMAIL" "$pubkey" )
curl -d "$json" https://api.github.com/user/keys?access_token=$GITHUB_TOKEN

Fetch suited.sh and run it, telling it which file(s) to use to setup your computer. They can be relative or absolute path, URLs or special github notation (as explained in the suitfile documentation).

curl -O https://raw.githubusercontent.com/norm/suited/latest/suited.sh
bash suited.sh github:wendy/suit:main.conf

Alternatively, an argument of a hyphen (-) means to use standard input as the suitfile:

echo "github:wendy/suit:Brewfile" | bash suited.sh -

Example suitfile

# setup xcode, homebrew and git
github:norm/suited:setup/install_xcode.sh
github:norm/suited:setup/homebrew.sh
github:norm/suited:setup/git.sh

# personal software
github:wendy/suit:Brewfile

# checkout code
repo wendy/suit
repo wendy/dotfiles

# lastly, ensure software is up to date
github:norm/suited:setup/software_update.sh

More documentation

You should read these before getting starting with suited:

• Using suited
• The suitfile in depth

I keep my setup in a separate public repo, to serve as a reference example of how to use suited.

Why yet another macOS/OSX bootstrapper

Why create another bootstrapper for your Mac computer? There are already many other systems, such as:

• battleschool
• boxen
• chef-osx
• dev-setup
• laptop
• mac-dev-playbook
• osxc
• strap
• vanilla Puppet
• workstation-chef

One reason to create this is to minimise the amount of stuff needed to write in order to setup a new laptop.

Another reason is frustration with the fragility of using software like puppet to only partially manage a machine — GitHub have abandoned using boxen (replacing it with strap) for similar reasons.

Another is that whilst something like strap (which is little more than a bit of shell setup and then using Homebrew) is almost what I wanted, I still missed the ability for multiple users to collaborate on setups, as when using boxen (a great example was the GDS boxen).

So here is suited (taken from the phrase suited and booted, but you can pretend it is a reference to making a computer suitable for use).

suited's Issues

Add testing

• integrate Travis
• stop master being pushed directly
• PRs require approval
• test basic commands
• test private files without GITHUB_TOKEN set
• test local and remote directories are traversed correctly

Directory setup now fails on `repo ...` commands without explicit destinations

Add a `touch` command

If a file needs to be created (regardless of content), you shouldn't need a shell script just for that.

Release 0.9

0.9 should contain at a minimum:

• no longer calling suited.sh again
• output updates
• suitfiles in directories
• recently PRd bug fixes

Release checklist:

• Create a release branch
• Check the changelog has all changes made on master actually listed;
  if not add them
• Update the changelog with the new version number
• PR/merge the release branch
• Tag the merge commit with the new version
• Checkout the latest branch, git merge --ff-only master, and push
• Close this issue as done

Add contributing guidelines

Improve the introductory documentation

At least one person using suited has blindly copied the "Wendy Testaburger" parts of the README, not realising that it was illustrative of what to do, not prescriptive. The introduction should be clearer, and further expand on why you might want to use suited.

Release 0.10

• Create a release branch
• Check the changelog has all changes made on master actually listed;
  if not add them
• Update the changelog with the new version number
• Update suited.sh with the new version number
• PR/merge the release branch
• Add a new release https://github.com/norm/suited/releases/new using
  the changelog as the description
• Checkout the latest branch, git merge --ff-only master, and push
• Close this issue as done

Add an `install` command

Sometimes new files/directories need to have specific permissions. Mimicking the install command is one way to achieve that.

Flag exiting on errors more clearly?

If brew bundle fails, for example, it looks like suited has finished running. It hasn't.

Test if mas-cli breaks on Yosemite (or earlier)

"All done" can be reported multiple times

When a subshell of suited is invoked, each reports "all done".

Easiest illustration of this:
echo 'github:norm/suit:user/norm/main.conf' | bash suited.sh -

Expand `~`, `$HOST`, etc before processing suitfile lines

It is done in some places, but not all, and not consistently (I tried to use $HOST in a symlink command and was confused for a moment).

Setup tests and run them in CI

Testing changes by hand is tedious. I should stop doing that. :)

Integrate with Slack

• create slack channel
• push GitHub notifications into the channel
• document channel for guests?

Setup python requirements automatically?

Feature request: pin repos to specific versions

This is really cool, I like that it might be more lightweight than Puppet/Boxen.

One feature that would help using other people's repos is to be able to pin to a specific version to prevent people from changing things underneath you. For example instead of using:

github:norm/suited:setup/password_after_screensaver.sh 

I would prefer to say:

github:norm/suited@fe24e4335ec1c8f08243b7322e04deebc8c2e3ac:setup/password_after_screensaver.sh 

The commit SHA gives me a decent level of confidence that I know what I'm about to run.

Add style guide

Add a `mkdir` command

Making a directory is a common enough operation, you shouldn't need a shell script just for that.