Get started

Note

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.

Note

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)

Warning

On macOS, all salt-ssh (and ./run.py) 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/run.py

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@github.com:open-contracting/deploy.git
git clone git@github.com:open-contracting/deploy-pillar-private.git deploy/pillar/private
git clone git@github.com:open-contracting/deploy-salt-private.git deploy/salt/private

3. Add your public SSH key to remote servers

Tip

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

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

This creates both public (~/.ssh/id_rsa.pub) 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:

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

4. Configure Salt for non-root user

Run:

./script/setup

This overwrites the files:

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

  • salt-config/master

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

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

  • Saltfile

Note

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

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

You’re now ready to Deploy a service.