Imagine having a fresh environment to configure every time. It could be a new computer, a PC gamer on top of your notebook, formatting your disk, or even creating a dual boot to play with Linux. You need to think about all the cool stuff you installed and configured in your primary machine to replicate and be up to speed on the other environment. Boring... right?
This project aims to help you (and me) map all the most important and common things we need as developers so we can quickly get up to speed using the most efficient environment we have.
The project uses a Salt Masterless approach to configure and automate everything we need for the local environment without the need for master and minion daemons/services. We could reach similar goals using tools like Ansible or other tools or even installing master and minion services to automate more targets that are not just your machine. Feel free to get inspired if you want to take a different route.
Quick overview of all automated installs (click to expand)
- GIT + configs
- Visual Studio Code + extensions
- Docker + configs
- Terminal using Zsh + configs + theme + plugins
- Python + Ruff + UV
- Hypervisors
- Vagrant
- General Tools
- General packages
- curl
- jq
- tree
- vim
- wget
- Extra
- GDM (GNOME Display Manager) + configs
- GRUB Customizer
- Extra fonts
- eza (alternative for
lscommand)
- Documentation about a few manual configurations
Coming soon ( as I have time 😄 )
- GIT + configs
- Visual Studio Code + extensions
- Docker
- Terminal using Zsh + configs + theme + plugins
- Python + Ruff + UV
- Hypervisors
- Vagrant
- General Tools
- 1Password
- Adobe Acrobat Reader
- BalenaEtcher
- Camtasia
- CleanMyMac X
- Discord
- Divvy
- Google Drive
- Google Chrome
- Imageoptim
- Keka
- Kindle
- NordVPN
- Notion
- Office 365 / Microsoft
- OneDrive
- Microsoft Word
- Microsoft Excel
- Microsoft Remote Desktop
- Paragon NTFS for Mac)
- Pixelmator Pro
- Postman
- Raspberry PI Imager
- Spotify
- Telegram
- The Unarchiver
- Vlc
- Vuescan
- WhatsApp Messenger
- Zoom
- General packages
- curl
- jq
- tree
- vim
- wget
- Extra
- Documentation about a few manual configurations
The easiest way to start is by installing salt via bootstrap script. Check Salt release notes page to pick your desired version.
Ubuntu (click to expand)
curl -o /tmp/bootstrap-salt.sh -L https://bootstrap.saltproject.io
# test the downloaded file
test $(sha256sum /tmp/bootstrap-salt.sh | awk '{print $1}') \
= $(curl -sL https://bootstrap.saltproject.io/sha256 | cat -) \
&& echo "OK" || echo "File does not match checksum"
# alternative for curl
wget -O /tmp/bootstrap-salt.sh https://bootstrap.saltproject.io
# test the downloaded file
test $(sha256sum /tmp/bootstrap-salt.sh | awk '{print $1}') \
= $(wget -qO- https://bootstrap.saltproject.io/sha256) \
&& echo "OK" || echo "File does not match checksum"
# install salt
## -P : Allow pip based installations
## -X : Do not start daemons after installation (to favor our masterless approach)
sudo sh /tmp/bootstrap-salt.sh -X -P stable 3006.8
# For Debian distros, like Ubuntu, we will need to manually stop the service
## Message from the script
## WARN: Not starting daemons on Debian based distributions is not working mostly because starting them is the default behaviour.
sudo systemctl stop salt-minion
# check if the service is stopped
sudo systemctl status salt-minion
# ensure the service will not start on the next reboot
sudo systemctl disable salt-minionmacOS (click to expand)
curl -o /tmp/bootstrap-salt.sh -L https://bootstrap.saltproject.io
# test the downloaded file
test $(shasum -a 256 /tmp/bootstrap-salt.sh | awk '{print $1}') \
= $(curl -sL https://bootstrap.saltproject.io/sha256 | cat -) \
&& echo "OK" || echo "File does not match checksum"
# install salt
## -P : Allow pip based installations
## -X : Do not start daemons after installation (to favor our masterless approach)
sudo sh /tmp/bootstrap-salt.sh -X -P stable 3006.8
# Once it's installed, open a new terminal before executing salt commandsEXTRA NOTES: You might get a dialog regarding python3 asking to install "command line developer tools" (please do so because it's helpful and will install essential initial tools like git - the installation might take a while)
You can run some quick and basic tests using the --local argument:
sudo salt-call --local test.ping
sudo salt-call --local test.versionsClone the project:
# SSH
git clone [email protected]:rcmoutinho/salt-local-dev.git
# HTTPS
git clone https://github.com/rcmoutinho/salt-local-dev.gitNOTE: You can also fork this project before to allow you to push all your custom changes to your project.
The Masterless approach means that instead of connecting to a Salt master to collect files and pillars (default configuration behavior with minion configuration file_client: remote), we will only rely on the local files removing the need of a minion daemon. This means we will only use the salt-call command line.
It's possible to force local calls using the argument --local and many other specific configurations, but using a Saltfile makes everything WAY simpler in this scenario.
Duplicate the reference Saltfile.template, in the root of this project, into Saltfile and define all the specific configurations you have. This configuration will help you typing less arguments when executing commands from the root of the project.
Depending on the OS (for example, macOS), it will only work when saving the file under ~/.salt/Saltfile. However, for other OS, like Ubuntu, this approach might not work because you always use sudo, which favors root user references. You can change the user minion configuration not to use root, but this can be a bit advanced for a simple setup we want here.
Regardless of your choice, we can apply the salt minion state later to make the file_client configuration permanent.
To simplify the project configuration with your personal data, duplicate the folder pillar/personal.template/ into pillar/personal/ and change the values to your preferences under pillar/personal/init.sls.
If you need to handle any extra secrets locally, you can improve security using GPG keys.
IMPORTANT: Ensure you know what you are doing before pushing your encrypted value, and NEVER commit your private GPG key or plaintext secrets. As a personal project, I recommend keeping personal data and encrypted secrets under the "pillar/personal" folder to avoid worrying much about your public repository content, considering this folder is ignored.
There is no point in rewriting the excellent salt documentation about GPG already available. This section will focus on the minimum you need to configure your keys on your local machine. It will be a one-time setup so you can encrypt/decrypt your secrets and still be able to version them.
sudo mkdir -p /etc/salt/gpgkeys
sudo chmod 0700 /etc/salt/gpgkeys
# It is an interactive command
# Make sure **NOT to add a password**, considering salt does not support it
sudo gpg --homedir /etc/salt/gpgkeys --gen-keyYou can now run the salt minion state to make masterless definitions permament. This would be optional in a way but it make simpler to ensure all the configurations you have for your salt setup.
# with Saltfile configured
sudo salt-call state.sls salt.minion
# without Saltfile configured
sudo salt-call --local --file-root /path/to/my/project/salt --pillar-root /path/to/my/project/pillar state.sls salt.minionIf you get an error like No matching sls found for 'salt.minion' in env 'base'. Please check your Saltfile or arguments regarding the file and pillar root. It must point correctly to the salt and pillar folders from this project.
You will also get errors regarding missing the personal pillar folder if you haven't configured it based on the template yet.
Once you have managed all the previous instructions, you should execute all states safely. Before applying all changes, you can run a test to understand all the potential changes.
NOTE: For macOS, you might need to log in to the AppStore before running all states. Processes that install apps via CLI require this access. Only previously downloaded apps can be installed. Any other will cause an error while trying to install.
# dry-run
sudo salt-call state.highstates test=True
# apply changes
sudo salt-call state.highstatesVoilà! Everything is now configured!
IMPORTANT: Keep in mind this code was developed to be idempotent. So after running once, following executions won't change the final result unless there is something to change (like a new software version in case we enforce the latest).
Find more about the project, extra configurations, faq, and more under the doc folder.
Supported and tested OS, so far:
- Ubuntu 20.04 LTS
- macOS Monterey 12.7.5