Need help with battleschool?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

418 Stars 42 Forks Apache License 2.0 134 Commits 14 Opened issues


Development environment provisioning using ansible, ala boxen -> puppet, kitchenplan -> chef

Services available


Need anything else?

Contributors list


Development environment provisioning using ansible, ala boxen which uses puppet and kitchenplan which uses chef Built on and for macs, but should be usable on Linux

See this blog post for some background.


#if needed
sudo easy_install pip

sudo pip install battleschool

install preview releases

sudo pip install

running battleschool for the first time

battle --config-file http://somesite/path/to/your/config.yml

installing on linux

NOTE: You'll need to install libyaml-dev

e.g. on ubuntu based systems

sudo apt-get install libyaml-dev    

As long as your

doesn't have a
section (see configuration below), you don't need to download or create a configuration for the first time.

running battleschool



NOTE: in the future, a default empty configuration will be created if you do not create one

mkdir ~/.battleschool

put the following in

and uncomment the items you want intstalled (remove the #)
    #- playbook.yml

url: #- name: playbook.yml # url:

git: - name: 'osx' repo: '' playbooks: #- adium.yml #- alfred.yml #- better-touch-tool.yml #- chrome-beta.yml #- dropbox.yml #- github.yml #- gitx.yml #- intellij-idea-ultimate.yml #- iterm2.yml #- java7.yml #- libreoffice.yml #- sequel-pro.yml #- skype.yml #- truecrypt.yml #- usb-overdrive.yml #- vagrant.yml #- virtualbox.yml #- xtra-finder.yml

Here is my config.yml

Here is my playbook.yml

explanation of ~/.battleschool/config.yml

local sources

    - playbook.yml

Any ansible playbooks located in

can be listed under local. Each playbook will be executed in order. This can be useful for custom configuration per workstation. (You could install apps with homebrew or macports if those are installed, for example)

url sources

    - name: playbook.yml

Playbooks located at a url. Each playbook will be executed in order. Helpful for bootstrapping (ie, the first time you run battleschool.

git sources

  - name: 'osx'
    repo: ''
       - adium.yml

Any git repo that hosts ansible playbooks (specific to battleschool or not) will work here. Each item under playbooks is the relative location to a playbook in the specified git repository. In the example above,

is in the root of the ansible-osx repository.

git repo sources

Directory Layout

The top level of the directory would contain files and directories like so:

local.yml                 # master playbook, after ansible-pull, automatically run, no need to list under playbooks
                          # NOT REQUIRED

dev.yml # playbook for dev ux.yml # playbook for ux chrome.yml # playbook for chrome

roles/ # standard ansible role hierarchy library/ # remote module definitions

See the roles docs for information about ansible roles and library is the location for placing custom ansible modules

the mac_pkg module

if you look most of the playbooks in this git repo you will see the use of the mac_pkg module. Mac apps are usually a pkg (or mpgk) installer, or the bare .app directory. They can be archived in a number of formats: DMG or zip commonly. Pkg files may not be archived at all. Less common formats (tar or 7zip) are not supported yet.

Lets look at adium.yml

- hosts: workstation

tasks: - name: install Adium mac_pkg: pkg_type=app url= archive_type=dmg sudo: yes

- hosts: workstation
this is required in each playbook as it targets the local workstation. Though this is generally arbitrary for most ansible users, it must be
in battleschool.

type must be pkg or app. Defaults to pkg

the url of the app to download, alternatively
may be used instead.

one of dmg, zip or none. Defaults to none.
The path to the app or pkg in the archive.

sudo: yes
required for mac_pkg tasks (this will prompt you to enter you sudo password only once)

NOTE: battleschool, currently does not install apps from the Apple App Store.

common battle options

I alias battle to

battle -K
-K, --ask-sudo-pass   ask for sudo password

Force update of the playbooks from a VCS such as git

-X, --update-sources      update playbooks from a version control system (vcs)

battle USAGE

$ battle -h
Usage: battle

Options: --acquire-only configure mac_pkg module to only aquire package (ie download only) --ask-become-pass ask for privilege escalation password -k, --ask-pass ask for SSH password --ask-su-pass ask for su password (deprecated, use become) -K, --ask-sudo-pass ask for sudo password (deprecated, use become) --ask-vault-pass ask for vault password -b, --become run operations with become (nopasswd implied) --become-method=BECOME_METHOD privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | runas ] --become-user=BECOME_USER run operations as this user (default=None) -C, --check don't make any changes; instead, try to predict some of the changes that may occur --config-dir=CONFIG_DIR config directory for battleschool (default=/.battleschool) --config-file=CONFIG_FILE config file for battleschool (default=/.battleschool/config.yml) -c CONNECTION, --connection=CONNECTION connection type to use (default=smart) -D, --diff when changing (small) files and templates, show the differences in those files; works great with --check -e EXTRA_VARS, --extra-vars=EXTRA_VARS set additional variables as key=value or YAML/JSON -f FORKS, --forks=FORKS specify number of parallel processes to use (default=5) -h, --help show this help message and exit -i INVENTORY, --inventory-file=INVENTORY specify inventory host file (default=/usr/local/share/battleschool/defaults/hosts) -l SUBSET, --limit=SUBSET further limit selected hosts to an additional pattern --list-hosts outputs a list of matching hosts; does not execute anything else --list-tasks do list all tasks that would be executed -M MODULE_PATH, --module-path=MODULE_PATH specify path(s) to module library (default=None) -o, --one-line condense output --private-key=PRIVATE_KEY_FILE use this file to authenticate the connection --step one-step-at-a-time: confirm each task before running -S, --su run operations with su (deprecated, use become) -R SU_USER, --su-user=SU_USER run operations with su as this user (default=root) (deprecated, use become) -s, --sudo run operations with sudo (nopasswd) (deprecated, use become) -U SUDO_USER, --sudo-user=SUDO_USER desired sudo user (default=root) (deprecated, use become) --syntax-check do a playbook syntax check on the playbook, do not execute the playbook -T TIMEOUT, --timeout=TIMEOUT override the SSH timeout in seconds (default=10) -t TREE, --tree=TREE log output to this directory -X, --update-sources update playbooks from sources(git, url, etc...) --use-default-callbacks use default ansible callbacks (to exec vars_prompt, etc.) -u REMOTE_USER, --user=REMOTE_USER connect as this user (default=sgibb) --vault-password-file=VAULT_PASSWORD_FILE vault password file -v, --verbose verbose mode (-vvv for more, -vvvv to enable connection debugging) --version show program's version number and exit

For more options see ansible-playbook -h


TODO: cleanup cli output

TODO: more docs

TODO: default to ask sudo pass (simpler options). Only don't ask if --no-sudo-pass is true

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.