Home

  _______  _____         _____ __   _ _______ _______  ______
  |______ |_____] |        |   | \  |    |    |______ |_____/
  ______| |       |_____ __|__ |  \_|    |    |______ |    \_

         2020 (c) MarcoMC - github.com/marcomc/splinter
An opinionated provisioning tool for macOS automated with Ansible

• What does Splinter do?
  • BASH script
  • Ansible playbook
• Use cases with step-by-step instructions
• Profiles
• Custom Profiles repositories
• Deployable packages
• Python environment to run Ansible

What does Splinter do?

Splinter uses a bash script to install the minimum requirements to run Ansible within a dedicated Python environment, then run an Ansible playbook that will run the full provisioning of a macOS system

You can customise your provisioning activating toggling modules and modifying attributes via the use of profiles.

BASH script

• Ask for current user password
  • will be used for sudo during the whole provisioning
• Enable passwordless sudo
• Check and fix install-dir path permissions
• Install requirements
  • Conda or Pyenv and Homebrew
• Activate Conda or Pyenv
• Install python 3.x
• Upgrade pip to the latest version
• install pip dependencies
  • ansible
  • wheel
  • passlib
• update Ansible Galaxy roles
• run Ansible Playbook
• restore path permissions
• disable passwordless sudo

Ansible playbook

• Allow passwordless sudo if it is not already active
• Disables Apps Quarantine for the time of the provisioning only
• Install GNU tar via Homebrew
• Update the current user Profile Picture
• Set the ComputerName & LocalHostName
• Install Sophos Antivirus Endpoint (if an installer URL or zip file are provided)
• Create a new employee's Account (target_user_id)
• Configure ssh for the new user:
  • Creates its RSA SSH key pair
  • Setup the ssh_config
    • Define some default parameters
    • Add an SSH proxy server definition (optional)
• Activate FileVault2
• Install/Configure Hombrew:
  • Allow multi-user administration allowing all members of the chosen group to Read/Write (by default it is admin group)
  • Enable Auto-updates
    • define a threshold to consider cached database still fresh
    • setup a LaunchAgent to refresh the cached database periodically
  • Install desired taps
  • Install desired packages
  • Install desired Cask applications
• Install global (system-wide) packages:
  • Install desired NPM packages
  • Install desired PIP packages
  • Install desired Composer packages
  • Install desired Ruby gems
• Configure macOS system-wide settings:
  • Application Firewall
  • Date & Time, Timezone & Formats
  • Display(s)
  • Energy Saver
  • Login Window
• Configure macOS user's settings (for targe_user_id)
  • Activity Monitor
  • App Store
  • Dashboard
  • Desktop and Screen Saver
  • Disk Image handling
  • Finder
  • Hot-Corners
  • Keyboard
  • Language and Region
  • Mission Control
  • Safari
  • SetupAssistant (chose to skip some or all setup questions)
  • Spotlight
  • Trackpad
• Restore dotfiles (3 distinct methods):
  • via a private dotfile repository
  • via Macprefs backup
  • via Mackup sync tool
• Install applications from the Mac App Store (MAS apps)
• Install applications from direct links (non-MAS apps)
• Install SetApp applications store (from which you can install additional apps)
• Run custom post-provision tasks

You can choose which of the above modules to run customising the the 'modules.yml' file in your profiles

Use cases with step-by-step instructions

1. Provision a Mac for a new employee
2. Build a backup Mac
3. Migrate to a new Mac
4. Rebuild a Mac to a clean state
5. Restore your Mac favourite settings and software
6. Create an additional account for your kids or partner

Profiles

Splinter supports 3 levels of profile listed here from least to most important:

1. marcomc.splinter_toolkit default values: This is a collection of sensible default values contained in the Ansible role marcomc.splinter_toolkit

2. profiles/base: This is a set of default values that you can customise and rename as you prefer.

   If you are handling many different profiles i.e. finance, developer, devops, fe-developer, marketing you can have a base default set with the common company defaults to apply to all new machines.

3. profiles/<role-profile>:

   These are specific role profiles where you can define only the settings that you want to customise for each role of machine or employee that will override some or all of the settings specified in your base profile.

   i.e. finance, developer, devops, fe-developer, marketing

Custom Profiles repositories

Splinter support custom profiles stored in a Github repository.

They can be download on-the-fly during the provisioning.

This is helpful for a central support team to maintain profiles to be used company-wise while letting the employees in a satellite office run their own provisioning

Deployable packages

If you are deploying a FileVaultMaster keychain file, make sure to remove the private key from it

Splinter can create deployable packages with pre-installed dependencies such as Python, Ansible, Galaxy roles and profiles to copied to the target machines. You could also include manually download installation packages for non-MacAppsStore applications (i.e. antivirus software)

Advantages:

1. reduce the provisioning time if you have a limited internet bandwidth
2. can configure pre-packages provisioning to distribute to various offices

Python environment to run Ansible

Python is provided by default via a custom Conda package

alternatively an on-the-fly Pyenv installation can be used as well.

Having Python running within a pre-configured project's specific environments means that the target system won't be polluted with any python package that might be undesired by the user.

To choose which python environment to run:

  ./plinter.sh --env [conda|pyenv] install .....

Conda makes the provisioning dependencies installation much faster because comes in a preconfigured package already loaded with Ansible and doesn't require any Pip package installation.