Get started


Only follow the Development Guides if you will be configuring or deploying servers. If you are simply using services, read the User Guides.

1. Install dependencies

Follow the Salt install guide to install Salt on your platform.


On at least macOS, you should:

  1. Change your login shell to /bin/bash:

    chsh -s /bin/bash
  2. If you use Terminal, also:

    1. Open the Settings… menu

    2. Set Shells open with: to Command (complete path):

    3. Enter the complete path to your preferred shell (for example, /opt/homebrew/bin/fish)

  3. Stop the Salt minion service:

    launchctl stop com.saltstack.salt.minion
  4. Disable the Salt Stack, Inc. login item (System Settings… > General > Login Items)


On macOS, all salt-ssh (and ./ commands need to be run with sudo. To run sudo without password:

  1. Edit the /etc/sudoers file:

    sudo visudo
  2. After the %admin          ALL = (ALL) ALL line, add, for example:

    %admin          ALL = (root) NOPASSWD: /usr/bin/ssh, /opt/salt/salt-ssh, /path/to/deploy/

Click must be available to Salt’s environment:

sudo salt-pip install click

2. Clone repositories

You must first have access to three private repositories. Contact an owner of the open-contracting organization on GitHub for access. Then:

git clone
git clone deploy/pillar/private
git clone deploy/salt/private
git clone deploy/salt/maintenance

3. Add your public SSH key to remote servers


To generate an SSH key pair (if they do not already exist):

ssh-keygen -t rsa -b 4096 -C ""

This creates both public (~/.ssh/ and private (~/.ssh/id_rsa) keys.

Add your public SSH key to the ssh.root list in the target’s Pillar file, or to the ssh.admin list in the pillar/common.sls file if you require root access to all servers. For example:

vi pillar/common.sls
git commit pillar/common.sls -m "ssh: Add public key for Jane Doe"
git push origin main

Then, ask James or Yohanna to deploy your public SSH key to the relevant servers. For example:

./ '*' state.sls_id root_authorized_keys core.sshd

4. Configure Salt for non-root user



This overwrites the files:

  • salt-config/master.d/localuser.conf

  • salt-config/master

  • salt-config/pki/ssh/

  • salt-config/pki/ssh/salt-ssh.rsa

  • Saltfile


On macOS, you might need to move Saltfile to ~/.salt/Saltfile.

This script assumes your SSH key pair is ~/.ssh/ and ~/.ssh/id_rsa.

You’re now ready to Deploy a service.