Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wikioasis/salt/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through getting WikiOasis Salt running on a fresh Salt master. By the end you will have the master configured, all minions reachable, and the base state applied across the fleet. The only hard prerequisite is a running Debian system designated as the Salt master — all other tooling is installed along the way.
This repository requires private pillar data (passwords, API keys, SSH keys) that is not committed to git. You must create pillar/private/init.sls on the master before applying any state that references secrets. See Private Pillar for details.
1

Clone the repository

Clone the repository to the Salt master. The conventional location on Debian is /srv/salt for states and /srv/pillar for pillar data, but WikiOasis uses a single git checkout and configures Salt to point at the subdirectories within it.
git clone https://github.com/wikioasis/salt.git /srv/wikioasis-salt
2

Install salt-master

Install the Salt master package from the official SaltProject repository. The minion package (salt-minion) should already be installed on every managed node.
# Add the SaltProject APT repository for Debian
curl -fsSL https://packages.broadcom.com/artifactory/api/security/keypair/SaltProjectKey/public \
  | gpg --dearmor -o /usr/share/keyrings/salt-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/salt-archive-keyring.gpg arch=amd64] \
  https://packages.broadcom.com/artifactory/saltproject-deb/ stable main" \
  > /etc/apt/sources.list.d/salt.list

apt-get update && apt-get install -y salt-master
3

Configure salt-master

Create or edit /etc/salt/master to point the master at the repository’s subdirectories. The file_roots key tells Salt where to find state files; pillar_roots tells it where to find pillar data.
# /etc/salt/master

# State files live in the salt/ subdirectory of the checkout
file_roots:
  base:
    - /srv/wikioasis-salt/salt

# Pillar data lives in the pillar/ subdirectory of the checkout
pillar_roots:
  base:
    - /srv/wikioasis-salt/pillar

# Allow minions to connect from the internal network
interface: 0.0.0.0

# Optional: auto-accept minions whose keys match a glob (not for production)
# autosign_grains_dir: /etc/salt/autosign_grains
After editing the configuration, restart the master:
systemctl restart salt-master
systemctl enable salt-master
4

Create the private pillar

The private pillar holds all secrets and is never committed to git. Copy the provided example to the correct location and fill in real values:
cp /srv/wikioasis-salt/pillar/private/init.sls.example \
   /srv/wikioasis-salt/pillar/private/init.sls

# Edit the file and replace every CHANGE_ME placeholder
$EDITOR /srv/wikioasis-salt/pillar/private/init.sls
At minimum, you must set the monitoring passwords and the mariadb.backup credentials before applying states that use them. See Private Pillar for the full list of required keys.
pillar/private/*.sls is listed in .gitignore. Never commit the populated file — it contains plaintext passwords and private SSH keys.
5

Accept minion keys

Each minion that connects to the master generates a key pair and sends its public key for acceptance. List pending keys and accept them:
# List all pending, accepted, and rejected keys
salt-key --list-all

# Accept a single minion
salt-key --accept mw-us-east-011

# Accept all pending keys at once (review first in production)
salt-key --accept-all
6

Verify connectivity

Confirm that all accepted minions are responsive before applying any state:
salt '*' test.ping
A healthy response looks like:
mw-us-east-011:
    True
mw-us-east-012:
    True
proxy-us-east-011:
    True
db-c1-us-east-021:
    True
# … and so on for every minion
7

Apply the base state

The base state configures the timezone, APT sources list, and APT preferences on every minion. It is the safest first state to apply and has no service-level side effects.
# Apply base to all minions
salt '*' state.apply base

# Or apply base to a single minion first as a smoke test
salt 'mw-us-east-011' state.apply base
Run with --output=mixed to see a compact summary that highlights only changes and failures, rather than the full verbose output.
8

Apply the users state

The users state creates system accounts, installs SSH public keys, and configures sudo groups (ops, mediawiki-admins) across the fleet.
salt '*' state.apply users

​
Next steps

Now that the master is running and minions are converged to the base state, explore the rest of the documentation:

Architecture

Understand how minion targeting, server roles, and the internal network fit together.

Pillar Data

Learn how to read and extend the pillar data that drives every state.

Top Files

See exactly which states and pillars are assigned to each minion pattern.

Private Pillar

Reference the full list of secrets that must be populated before going live.

Build docs developers (and LLMs) love

Get started for freeTalk to us