Provision a Mac for a new employee

Description
Prepare the provisioning
Provision the new machine

Description

Provision a machine with the company defined standards for settings and software with different flavours for each department or employee role.

Configure a provisioning package on the system administrator and distribute it to the machines that you have to provision.

Prepare a provisioning package configured with:

The base profile with standard settings that will apply to all the machine.
and role profiles with settings dedicated to the department or employee role.
configuration files for each machine
FileVault2 encryption certificates
Antivirus installer (only Sophos Endpoint is supported at the moment)

Profiles example:

base profile:

Common admin username and profile picture.
Corporate FileVault2 recovery key certificate or keychain file.
Company unified desktop picture.
Default applications set: Slack, Skype, LastPass, Jira Client, Google Drive File Stream, Chrome, Firefox, Zoom...

admin role:

Additional applications set: Microsoft Office, Citrix...

developer role:

Additional applications set: Atom, Visual Studio, iTerm2, Docker Desktop, MacVim, Tunnelblick, VirtualBox ...
Homebrew packages: awscli, lastpass-cli, curl ...
System settings: show all extensions, show hidden files, show ~/Library folder ...

creative role:

Additional applications set: Adobe Creative Suite ...

Prepare the provisioning

Install Splinter in the System Administrator computer

follow the installation instructions.

Configure your custom profiles

In ./splinter/profiles/ you will find two initial example profiles:

base
example

Customise your base common profile

This profile is meant to contain common settings for all your computers and employees.

Create as many role profiles as you need.

You can create a role profile for each department of your company or for any specific employee role

 for example:
 
 * administration
 * human-resources
 * marketing-team
 * board-memeber
 * developer
 * devops
 * fe-developer
 * qa-team

You can modify or copy the base and example profiles provided with the initial splinter project folder to create your own profiles.

Enable and configure the desired provisioning modules

In your base profile include the full set of configuration files with the full set of configuration attributes set the most common desired values.
In your role profiles include only the configuration files and attributes meant to override the base profile values according to specific needs of an employee role or machine use.

Any role profile setting will be merged with the settings defined in the base profiles(s). The values defined in a role profile will have priority over the ones defined in the base profile

Toggle the modules you want to use for the provisioning in <custom_profile>/modules.yml
Toggle the system preferences you want to customise <custom_profile>/system_preferences.yml

Each module has its own configuration file with its own attributes and toggles that you can customise.

    # examples of profiles
    
    profiles/
    │
    ├── base (common profile)
    │   │
    │   ├── current_user.yml
    │   ├── dotfiles.yml
    │   ├── extra_packages.yml
    │   ├── filevault_option.yml
    │   ├── homebrew.yml
    │   ├── mac_app_store.yml
    │   ├── macos_apps_list.yml
    │   ├── modules.yml
    │   ├── new_user.yml
    │   ├── post_provision.yml
    │   ├── sophos-endpoint.yml
    │   ├── ssh_config.yml
    │   └── system_preferences.yml
    │
    ├── marketing (role profile)
    │   │
    │   ├── macos_apps_list.yml
    │   ├── modules.yml
    │   └── system_preferences.yml
    │
    └── developer (role profile)
        │
        ├── homebrew.yml
        ├── modules.yml
        ├── new_user.yml
        ├── ssh_config.yml
        └── system_preferences.yml

It is possible to pre-install a large variety of Mac applications of common user specifying them as Homebrew Casks list:

    # file: <custom-profile>/homebrew.yml
    
    homebrew_cask_apps:
        - atom
        - docker
        - firefox
        - github
        - google-backup-and-sync
        - google-chrome
        - google-drive-file-stream
        - iterm2
        - ...

For profiles set up for developers in general, it can be convenient to specify a list of default of homebrew packages to pre-install common Unix tools used within the company.

    # file: <custom-profile>/homebrew.yml
    
    homebrew_installed_packages:
        - autoconf
        - bash-completion
        - gnu-tar
        - awscli
        - cmake
        - composer
        - ...

Upload your custom profiles to your Github account

This is optional.

Once you have created your profiles you can push your profiles to a Github repository so that they can be maintained and reused in time and across offices.

This is particularly useful if you are delegating the provisioning of a new machine to people in different offices and still keep a cross-company standard

Uploading profiles to a Github repository is not mandatory but is recommended

If you name the profiles repository splinter-profiles it won't be necessary to specify the custom_profiles_repo value in the splinter's config file

Review the instruction about how to create a custom profiles repository and store it in GitHub.

Create your custom configuration files

This is optional.

You can create any number fo splinter configuration file in (.cfg INI format) one for each machine that you want to configure and they can be named as you like:

The config file contains the only settings related to the new user (if any) and the machine's name.
All the attributes set in the config file can be also specified via splinter command-line parameters
If you have a config file named splinter.cfg will be loaded automatically.
If you have a configuration file but you do not want to load it automatically DO NOT NAME IT splinter.cfg
You can choose not to use any configuration file and only run with command-line parameters.
Config file and command-line parameters are NOT MUTUALLY EXCLUSIVE:

you can use a configuration file and specify some parameters via command line to complement or override the former

Command-line parameters have priority over the attributes specified in the config file.

  # file: slinter.cfg
  verbose="yes"
  
  custom_profiles_repo_account="mycompany"
  
  custom_profiles_repo="splinter-profiles"
  
  base_profile="common-profile"
  
  role_profile="developer-profile"
  
  new_user_username="newemployee"
  
  new_user_fullname="New Employee"
  
  new_user_password_cleartext="password"

  computer_name="New-Mac-For-New-Employee"

See the content of example-splinter.cfg for a detailed description of the parameters.

Equivalent command-line parameters

    ./splinter -v provision -u 'newemployee' -f 'New Employee' -p 'password' -b 'common-profile' -r 'developer-profile' -a 'mycompany' -g 'splinter-profiles' -h 'New-Mac-For-New-Employee'

Note: For the computer name to applied, make sure to set:

    # file: <base_profile>/modules.yml

    configure_system: yes

Setup FileVault2 encryption

Enable this FileVault2 in your base profile:

    # file: <base_profile>/modules.yml
    
    configure_filevault: yes

Follow these instructions to activate FileVault2 with an Institutional or Personal Recovery Key

Add Sophos Anti-Virus Endpoint installer

If you have a company subscription for Sophos Anti-Virus Endpoint

Download the macOS Sophos endpoint installer from your Sophos Cloud account
Save the installer archive as
```
 (splinter project)/files/sophos_endpoint/SophosInstaller.zip
```
make sure that the name and path is exactly the above

Enable Sophos configuration on your 'base' profile:

     # file: <base_profile>/modules.yml
     
     configure_sophos_endpoint:      no

When creating the provisioning package the installer will be included in it.

The SophosInstaller.zip should NOT be posted on a public link because it contains your company-specific identified that will connect the provisioned machine to your Sophos account.

Add custom profile and desktop background pictures

Profile Pictures

You can add a custom and distinct company profile pictures (i.e. the company logo) for both the new employee account and the 'admin' account from which you are running the provisioning (referred to as current_user).

Load those files in .jpg or .png formats into:

 `(splinter project)/files/profile_pictures/`

Specify their path/name in the configuration files:

 # file: <base_profile>/current_user.yml
 
 current_user_profile_picture: "files/profile_pictures/company_logo.png"
 

 # file: <base_profile>/new_user.yml
 
 new_user_profile_picture_path: 'files/profile_pictures/department_logo.png'

Desktop picture

You can also add a custom company desktop background image

Load the background image files in .jpg or .png formats into:
```
 `(splinter project)/files/`
```

Specify its path/name in the configuration files:

 # file: <base_profile>/system_preferences.yml
 
 Configure_DesktopScreenSaver:  yes
 DesktopScreenSaver_BackGroundImage: "files/desktop_pictures/custom_desktop_image.jpg"

Create the provisioning package

Now that you have added all your custom settings and files to the project folder you can create a provisioning package that you can reuse when needed.

Make sure to remove the keychain file and the master key (and any other sensitive information) from the project folder before packaging it.

    ./splinter create package

will create (splinter project)/SplinterProvision.dmg with a rough size of 600MB

Store the provisioning package in a company shared storage where other colleagues could also access it, for example, Google Drive

Provision the new machine

When provisioning a new employee machine it is recommended to run the provision with an 'admin' account distinct from the new employee's account you will create.

New machine preparation steps

Login in the new machine as the company admin account, the first account you create in the machine, not the new employee user account.
Add the Terminal application (located in /Applications/Utilities/) to the "Full Disk Access" policy

a. Open System Preferences -> Security & Privacy -> Privacy -> Full Disk Access

b. Authenticate to unlock the list of allowed applications

c. Add Terminal to the list of allowed apps, save and close.
Connect to a WiFi network.
Transfer a copy of the SplinterProvision.dmg provisioning archive to the new machine:

option 1: transfer the directory using Share->AirDrop (you need to make the new machine discoverable by everyone).
option 2: transfer with a USB stick.

Mount the provisioning archive

New machine provisioning

from the Terminal applicatione access the mounted diskimage

cd /Volumes/SplinterProvision

run splinter:

If you are using splinter.cfg
```
  ./splinter provision
```
If you are using a custom-name configuration file:
```
  ./splinter provision -c custom-name.cfg
```

If you are NOT using a configuration file:

  # You need to escape spaces when defining the user's full name
  ./splinter provision -u newemployee -f 'Full Name' -p 'cleartextnewuserpass' -b base-profile -r role-profile -h 'Computer-Name'

Splinter will request you to enter the current user account (to be used as sudo password throughout the whole process).

The rest of the provisioning can be mostly unattended but a few applications might require some system privacy authorisation, for instance vagrant and if you do not allow that in time and the installation fail you can re-run the brew installation command or re-run splinter

During the deployment a few applications might request authorisation to run so do not leave the computer completely unattended.

Post Provisioning manual Steps

You do not need to login into the new employee account because all settings have been set by Splinter, included muting all the Setup Assistant first-login panels.

Authorise "Virtualbox" kext if you installed it via homebrew or macos_apps list

This applies only if you have installed Oracle's Virtualbox

Go to System Preferences -> Security & Privacy -> General
Click the Allow button next to the request of authorisation for "Oracole America, Inc." software
re-run VirtualBox installation, this time it should succeed without errors

brew cask reinstall VirtualBox