Installing Salt for development¶

Running a self-contained development version¶

During development it is easiest to be able to run the Salt master and minion that are installed in the virtualenv you created above, and also to have all the configuration, log, and cache files contained in the virtualenv as well.

The /path/to/your/virtualenv referenced multiple times below is also available in the variable $VIRTUAL_ENV once the virtual environment is activated.

Copy the master and minion config files into your virtualenv:

mkdir -p /path/to/your/virtualenv/etc/salt/pki/{master,minion}
cp ./salt/conf/master ./salt/conf/minion /path/to/your/virtualenv/etc/salt/

Edit the master config file:

1. Uncomment and change the user: root value to your own user.

2. Uncomment and change the root_dir: / value to point to /path/to/your/virtualenv.

3. Uncomment and change the pki_dir: /etc/salt/pki/master value to point to /path/to/your/virtualenv/etc/salt/pki/master

4. If you are running version 0.11.1 or older, uncomment, and change the pidfile: /var/run/salt-master.pid value to point to /path/to/your/virtualenv/salt-master.pid.

5. If you are also running a non-development version of Salt you will have to change the publish_port and ret_port values as well.

Edit the minion config file:

1. Repeat the edits you made in the master config for the user and root_dir values as well as any port changes.

2. Uncomment and change the pki_dir: /etc/salt/pki/minion value to point to /path/to/your/virtualenv/etc/salt/pki/minion

3. If you are running version 0.11.1 or older, uncomment, and change the pidfile: /var/run/salt-minion.pid value to point to /path/to/your/virtualenv/salt-minion.pid.

4. Uncomment and change the master: salt value to point at localhost.

5. Uncomment and change the id: value to something descriptive like "saltdev". This isn't strictly necessary but it will serve as a reminder of which Salt installation you are working with.

6. If you changed the ret_port value in the master config because you are also running a non-development version of Salt, then you will have to change the master_port value in the minion config to match.

Start the master and minion, accept the minion's key, and verify your local Salt installation is working:

cd /path/to/your/virtualenv
salt-master -c ./etc/salt -d
salt-minion -c ./etc/salt -d
salt-key -c ./etc/salt -L
salt-key -c ./etc/salt -A
salt -c ./etc/salt '*' test.version

Running the master and minion in debug mode can be helpful when developing. To do this, add -l debug to the calls to salt-master and salt-minion. If you would like to log to the console instead of to the log file, remove the -d.

zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/
var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc"
is longer than 107 characters (sizeof(sockaddr_un.sun_path)).

# check your current limit
ulimit -n

# raise the limit. persists only until reboot
# use 'limit descriptors 2047' for c-shell
ulimit -n 2047

GENERATE_SALT_SYSPATHS=1 pip install --global-option='--salt-root-dir=/path/to/your/virtualenv/' \
    -e ./salt   # the path to the salt git clone from above

GENERATE_SALT_SYSPATHS=1 WRITE_SALT_VERSION=1 pip install --global-option='--salt-root-dir=/path/to/your/virtualenv/' \
    -e ./salt   # the path to the salt git clone from above

MIMIC_SALT_INSTALL=1 pip install --global-option='--salt-root-dir=/path/to/your/virtualenv/' \
    -e ./salt   # the path to the salt git clone from above

Installing Salt from the Python Package Index¶

If you are installing using easy_install, you will need to define a USE_SETUPTOOLS environment variable, otherwise dependencies will not be installed:

USE_SETUPTOOLS=1 easy_install salt

Editing and previewing the documentation¶

You need sphinx-build command to build the docs. In Debian/Ubuntu this is provided in the python-sphinx package. Sphinx can also be installed to a virtualenv using pip:

pip install Sphinx==1.3.1

Change to salt documentation directory, then:

cd doc; make html

• This will build the HTML docs. Run make without any arguments to see the available make targets, which include html, man, and text.

• The docs then are built within the docs/_build/ folder. To update the docs after making changes, run make again.

• The docs use reStructuredText for markup. See a live demo at http://rst.ninjs.org/.

• The help information on each module or state is culled from the python code that runs for that piece. Find them in salt/modules/ or salt/states/.

• To build the docs on Arch Linux, the python2-sphinx package is required. Additionally, it is necessary to tell make where to find the proper sphinx-build binary, like so:

make SPHINXBUILD=sphinx-build2 html

• To build the docs on RHEL/CentOS 6, the python-sphinx10 package must be installed from EPEL, and the following make command must be used:

make SPHINXBUILD=sphinx-build html

Once you've updated the documentation, you can run the following command to launch a simple Python HTTP server to see your changes:

cd _build/html; python -m SimpleHTTPServer

Running unit and integration tests¶

Run the test suite with following command:

./setup.py test

See here for more information regarding the test suite.

Issue and Pull Request Labeling System¶

SaltStack uses several labeling schemes to help facilitate code contributions and bug resolution. See the Labels and Milestones documentation for more information.