Skip to content
🐳 Dockerized SaltStack Master
Shell Dockerfile Makefile
Branch: master
Clone or download

SaltStack Master v3000_1

Dockerfile to build a SaltStack Master image for the Docker opensource container platform.

SaltStack Master is set up in the Docker image using the install from git source method as documented in the the official bootstrap documentation.

For other methods to install SaltStack please refer to the Official SaltStack Installation Guide.

Table of Contents


Automated builds of the image are available on Dockerhub and is the recommended method of installation.

docker pull cdalvaro/saltstack-master:3000_1

You can also pull the latest tag which is built from the repository HEAD

docker pull cdalvaro/saltstack-master:latest

or from too.

docker pull

Alternatively you can build the image locally.

docker build -t cdalvaro/saltstack-master

Quick Start

The quickest way to get started is using docker-compose.


Start SaltStack master using:

docker-compose up --detach

Alternatively, you can manually launch the saltstack-master container:

docker run --name salt_master --detach \
    --publish 4505:4505/tcp --publish 4506:4506/tcp \
    --env 'SALT_LOG_LEVEL=info' \
    --volume $(pwd)/roots/:/home/salt/data/srv/ \
    --volume $(pwd)/keys/:/home/salt/data/keys/ \


Custom Recipes

In order to provide salt with your custom recipes you must mount the volume /home/salt/data/srv/ with your roots directory.

Minion Keys

Minion keys can be added automatically on startup to SaltStack master by mounting the volume /home/salt/data/keys and copying the minion keys inside keys/minions/ directory.

It is also important to know that, in order to keep your keys after removing the container, the keys directory must be mounted.

mkdir -p keys/minions
rsync root@minion1:/etc/salt/pki/minion/ keys/minions/minion1

docker run --name salt_master -d \
    --publish 4505:4505/tcp --publish 4506:4506/tcp \
    --env 'SALT_LOG_LEVEL=info' \
    --volume $(pwd)/roots/:/home/salt/data/srv/ \
    --volume $(pwd)/keys/:/home/salt/data/keys/ \

Master Signed Keys

It is possible to use signed master keys by establishing the environment variable SALT_MASTER_SIGN_PUBKEY to True.

docker run --name salt_stack --detach \
    --publish 4505:4505/tcp --publish 4506:4506/tcp \
    --env 'SALT_LOG_LEVEL=info' \
    --volume $(pwd)/roots/:/home/salt/data/srv/ \
    --volume $(pwd)/keys/:/home/salt/data/keys/ \

The container will create the master_sign key and its signature. More information about how to configure the minion service can be found here.

Additionally, you can generate new keys by executing the following command:

docker run --name salt_stack -it --rm \
    --volume $(pwd)/keys/:/home/salt/data/keys/ \
    cdalvaro/saltstack-master:3000 app:gen-signed-keys other_master_sign

The newly created keys will appear inside keys/generated/other_master_sign directory.

Host Mapping

Per default the container is configured to run salt-master as user and group salt with uid and gid 1000. From the host it appears as if the mounted data volumes are owned by the host's user/group 1000 and maybe leading to unfavorable effects.

Also the container processes seem to be executed as the host's user/group 1000. The container can be configured to map the uid and gid of git to different ids on host by passing the environment variables USERMAP_UID and USERMAP_GID. The following command maps the ids to the current user and group on the host.

docker run --name salt_stack -it --rm \
    --env "USERMAP_UID=$(id -u)" --env "USERMAP_GID=$(id -g)" \
    --volume $(pwd)/roots/:/home/salt/data/srv/ \
    --volume $(pwd)/keys/:/home/salt/data/keys/ \

Git Fileserver

This image uses GitPython and PyGit2 as gitfs backends to allow Salt to serve files from git repositories.

It can be enabled by adding gitfs to the fileserver_backend list (see Available Configuration Parameters), and configuring one or more repositories in gitfs_remotes.


The default name for the ssh key is gitfs_ssh but it can be changed with the env variables SALT_GITFS_SSH_PRIVATE_KEY and SALT_GITFS_SSH_PUBLIC_KEY.

This keys must be placed inside /home/salt/data/keys directory.


You can create an ssh key for pygit2 with the following command:

ssh-keygen -f gitfs_pygit2 -C ''

Place it wherever you want inside the container and specify its path with the configuration parameters: gitfs_pubkey and gitfs_privkey in your .conf file.

For example:

gitfs_provider: pygit2
gitfs_privkey: /home/salt/data/keys/gitfs/gitfs_ssh
gitfs_pubkey: /home/salt/data/keys/gitfs/

Important Note

If you get the following error while using gitfs with pygit2

_pygit2.GitError: Failed to authenticate SSH session: Unable to send userauth-publickey request

look if your private key hash empty lines at the bottom of the file and suppress them for solving the error.


Salt logs are accessible by mounting the volume /home/salt/data/logs/.

Inside that directory you could find supervisor/ logs and salt/ logs:

docker run --name salt_master --detach \
    --publish 4505:4505/tcp --publish 4506:4506/tcp \
    --env 'SALT_LOG_LEVEL=info' \
    --volume $(pwd)/roots/:/home/salt/data/srv/ \
    --volume $(pwd)/keys/:/home/salt/data/keys/ \
    --volume $(pwd)/logs/:/home/salt/data/logs/ \

Check Available Configuration Parameters section for configuring logrotate.

Available Configuration Parameters

Please refer the docker run command options for the --env-file flag where you can specify all required environment variables in a single file. This will save you from writing a potentially long docker run command. Alternatively you can use docker-compose.

Below is the list of available options that can be used to customize your SaltStack master installation.

Parameter Description
DEBUG Set this to true to enable entrypoint debugging.
TIMEZONE Set the container timezone. Defaults to UTC. Values are expected to be in Canonical format. Example: Europe/Madrid. See the list of acceptable values.
SALT_LOG_LEVEL The level of messages to send to the console. One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'. Default: warning
SALT_LOG_ROTATE_FREQUENCY Logrotate frequency for salt logs. Available options are 'daily', 'weekly', 'monthly', and 'yearly'. Default: weekly
SALT_LOG_ROTATE_RETENTION Keep x files before deleting old log files. Defaults: 52
SALT_LEVEL_LOGFILE The level of messages to send to the log file. One of 'garbage', 'trace', 'debug', info', 'warning', 'error', 'critical'. Default: warning
SALT_MASTER_SIGN_PUBKEY Sign the master auth-replies with a cryptographic signature of the master's public key. Possible values: 'True' or 'False'. Default: False
SALT_MASTER_USE_PUBKEY_SIGNATURE Instead of computing the signature for each auth-reply, use a pre-calculated signature. This option requires SALT_MASTER_SIGN_PUBKEY set to 'True'. Possible values: 'True' or 'False'. Default: True
SALT_MASTER_SIGN_KEY_NAME The customizable name of the signing-key-pair without suffix. Default: master_sign
SALT_MASTER_PUBKEY_SIGNATURE The name of the file in the master's pki-directory that holds the pre-calculated signature of the master's public-key. Default: master_pubkey_signature
SALT_MASTER_ROOT_USER Forces salt-master to be runned as root instead of salt. Default: False
SALT_GITFS_SSH_PRIVATE_KEY The name of the ssh private key for gitfs. Default: gitfs_ssh
SALT_GITFS_SSH_PUBLIC_KEY The name of the ssh public key for gitfs. Default:
USERMAP_UID Sets the uid for user salt to the specified uid. Default: 1000.
USERMAP_GID Sets the gid for user salt to the specified gid. Default: 1000.

Any parameter not listed in the above table and available in the following link, can be set by creating the directory config and adding into it a .conf file with the desired parameters:

mkdir config
cat > config/ports.conf << EOF
# The tcp port used by the publisher:
publish_port: 3505
# The port used by the communication interface.
ret_port: 3506

docker run --name salt_master -d \
    --publish 3505:3505/tcp --publish 3506:3506/tcp \
    --env 'SALT_LOG_LEVEL=info' \
    --volume $(pwd)/roots/:/home/salt/data/srv/ \
    --volume $(pwd)/keys/:/home/salt/data/keys/ \
    --volume $(pwd)/config/:/home/salt/data/config/ \


To test which salt minions are listening the following command can be executed directly from the host machine:

docker exec -it salt_master salt '*'

Then, you can apply salt states to your minions:

docker exec -it salt_master salt '*' state.apply [state]

Shell Access

For debugging and maintenance purposes you may want access the container shell. If you are using docker version 1.3.0 or higher you can access a running container shell using docker exec command.

docker exec -it salt_master bash


You can’t perform that action at this time.