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 Salt#

On macOS, using Homebrew, install Salt and Salt SSH with:

brew install salt

If you encounter issues, try installing with pip:

pip install --no-deps -r requirements.txt

For other operating systems and package managers, see this page (or this page) to install a recent version (2019 or later).

You must use Salt with Python 3. If your system package uses Python 2, install salt-ssh with pip into a Python 3 virtual environment.

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#

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/kingfisher.sls
git commit pillar/kingfisher.sls -m "ssh: Add public key for Jane Doe"
git push origin main

Then, ask a colleague 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#

Unless your local user is the root user, run:


This script assumes your SSH keys are ~/.ssh/id_rsa and ~/.ssh/

You’re now ready to Deploy a service.