(Powered by CICD-Tools.)
An example Mac Maker profile.
Use Mac Maker to apply this profile to a Mac that is ready to setup.
The template has generated you a development environment for a Mac Maker machine profile, with functional CI.
The default configuration has some excellent functionality out of the box:
- Installs the Homebrew cli tools and the content of the centralized package manifest in the profile/vars/main.yml file.
- A functional ClamAV install to protect you against malicious downloads.
- Node.js and Python, managed by asdf.
- Activate these language installs by following these instructions for your shell.
Extend this further by mixing and matching Ansible roles in the profile/install.yml file.
- To get the most out of your ClamAV install, make sure you grant it "Full Disk Access".
- Please take a quick look at the documentation here.
An OSX machine is of course the best platform to development your profile on, although you could probably use a Linux or BSD machine in a pinch.
You'll need Python 3.9 or later, and a container runtime environment such as Docker or Colima is strongly recommended.
Please see the complete template guide here.
Start here, it's really much simpler than you might think.
To start branching out, and really customizing things, get familiar with the following files:
- install.yml
- This is the main ansible playbook that will be run when you "Apply" this profile.
- requirements.yml
- This is configuration for ansible-galaxy dependencies.
- If you add additional roles, include them here, so your Profile includes everything it needs.
- Make sure to read the documentation any new roles and add the required variables to your main vars file.
The more customized your want your profile to become, the more you'll benefit from reading up on ansible.
There some configuration files you can fine tune as you see fit:
- .ansible-lint
- This is configuration for ansible-lint, which is used in the included GitHub CI pipeline.
- .yamllint.yml
- This is configuration for yamllint, which is used in the included GitHub CI pipeline.
The profile folder contains a special __precheck__ sub-folder with configuration used by Mac Maker to help end users apply the Profile to their machines.
Please read the Mac Maker Profile documentation for details on this. (It's a quick read.)
Mac Maker can work with public GitHub repositories, or with privately maintained spec.json files.
The Profile has a specific directory structure, but the spec.json file lets you mix and match where the directories and files are. It's a bit inflexible in certain ways, because it requires absolute paths, but this makes it ideal to work off a USB stick or any portable media.
When developing your profile locally, it's handy to setup a spec.json file that points to all the locations you need, so you can run Mac Maker to test.
(A common use case for spec.json files, is to clone a private git repository to a USB key, and configure the spec.json to point to the USB key locations.)
Please read the Mac Maker Job Spec documentation for details on this. (It's a quick read.)
Take care not to check in any privileged content such as passwords, or api keys to your profile. This is especially true if you're working with a public GitHub repository.
- The recommended best practice to work around this is to use environment variables. These are easily loaded into your shell before your run Mac Maker.
- This gives you the ability to parameterize certain aspects of your profile that may differ from machine to machine.
- Use Mac Maker's precheck functionality to document your profile's environment variables.
In practice this might mean keeping a small shell script that sets variables somewhere safe (such as an encrypted USB key):
#!/bin/bash
export MY_SECRET_VALUE="very secret"Before applying your profile, you would insert your USB key and source your shell script:
$ source /Volumes/USB/my_secret_script.sh
$ ./mac_makerYour environment variables will then be accessible inside Ansible configuration:
---
- name: Read My Secret
ansible.builtin.set_fact:
ansible_variable: "{{ lookup('env', 'MY_SECRET_VALUE') }}"You can find simple examples of this in the example profile here.
- Ansible also has an encryption system called vault which is used to encrypt files containing sensitive data.
- This would allow you to encrypt and decrypt yaml files containing sensitive material- but I would still recommend NOT making these files public.
- If you're working with securely stored vault files, you can use the
ANSIBLE_VAULT_PASSWORD_FILEenvironment variable documented here to decrypt your data during installation.
Poetry is leveraged to manage the Python dependencies:
You can also conveniently execute commands inside the Python virtual environment by using: poetry run [my command here]
The python library pre-commit is installed during templating with a few useful initial hooks.
This hooks depend on the presence of a container runtime such as Docker or Colima on your development machine.
Complete documentation on these hooks can be found here.
Certain versions of the Ansible tool chain may use these folders, which you would be best to avoid:
- .ansible/
- .cache/
- profile/.ansible/
- profile/.cache/
Mac Maker itself also writes some data overtop of the role (ephemerally at run time) in order to process it, this means there are a few paths that you should shy away from using:
- spec.json *
- profile/.mac_maker/
- profile/collections/ *
- profile/env/ *
- profile/inventory/ *
- profile/roles/ *
* (these paths are marked for deprecation, soon freeing them up for use)
An MIT license has been generated for you by default, feel free to discard/change as you see fit.