cdist/docs/web/cdist/install.mdwn

[[!meta title="How to install cdist"]]
[[!toc levels=3]]

## Requirements

### Source Host

This is the machine you use to configure the target hosts.

 * /bin/sh: A posix like shell (for instance bash, dash, zsh)
 * Python >= 3.2
 * SSH client
 * Asciidoc and xsltproc (for building the manpages)

### Target Hosts

 * /bin/sh: A posix like shell (for instance bash, dash, zsh)
 * SSH server

## Install cdist

You can install cdist either from git or as a python package.

### From git

Cloning cdist from git gives you the advantage of having
a version control in place for development of your own stuff
immediately.

To install cdist, execute the following commands:

    git clone https://github.com/ungleich/cdist.git
    cd cdist
    export PATH=$PATH:$(pwd -P)/bin

From version 4.2.0 cdist tags and github releases are signed.
You can get GPG public key used for signing [here](/software/cdist/pgp-key-EFD2AE4EC36B6901.asc).

#### Available versions in git

 * The active development takes place in the **master** branch
 * The current stable version can be found in the **2.0** branch
 * The upcoming stable version can be found in the **2.1** branch

Other branches may be available for features or bugfixes, but they
may vanish at any point. To select a specific branch use

    # Generic code
    git checkout -b <localbranchname> origin/<branchname>

So for instance if you want to use and stay with version 2.0, you can use

    git checkout -b 2.0 origin/2.0

#### Git Mirrors

If the main site is down, you can acquire cdist from one of the following sites:

 * git://github.com/telmich/cdist.git ([github](https://github.com/telmich/cdist))
 * git://git.code.sf.net/p/cdist/code ([sourceforge](https://sourceforge.net/p/cdist/code))

#### Building and using documentation (man and html)

If you want to build and use the documentation, run:

    make docs

Documentation comes in two formats, man pages and full HTML
documentation. Documentation is built into distribution's
docs/dist directory. man pages are in docs/dist/man and
HTML documentation in docs/dist/html.

If you want to use man pages, run:

    export MANPATH=$MANPATH:$(pwd -P)/docs/dist/man

Or you can move manpages from docs/dist/man directory to some
other directory and add it to MANPATH.

Full HTML documentation can be accessed at docs/dist/html/index.html.

You can also build manpages for types in your ~/.cdist directory:

    make dotman

Built manpages are now in docs/dist/man directory. If you have
some other custom .cdist directory, e.g. /opt/cdist then use:

    DOT_CDIST_PATH=/opt/cdist make dotman


### Python Package

Cdist is available as a python package at
[PyPi](http://pypi.python.org/pypi/cdist/). You can install it using

    pip install cdist

## Use cdist

[[Dig into the documentation|documentation]] to get started with cdist!

[[!tag cdist unix]]