View on GitHub


Test Coverage

![Converge Logo](docs/static/images/logo/converge_logo.png)

Converge is a configuration management tool that makes it easy to manage servers,
laptops and other devices.

Key features:

- Easy to install and run. A single binary and configuration file is all you need.
- Resources to make changes on your system: docker images and containers, users
and groups, systemd, and more. The Resource Reference at
[]( has a complete list of resources
and their configuration settings.
- A powerful graph engine that automatically generates dependencies and
runs tasks in parallel.
- API-first communication using [grpc](
- Module verification: only run trusted modules.

![Converge Graph](examples/docker-swarm-mode/graphs/main.png)

[![Slack Status](](
[![Code Climate](](

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
**Table of Contents**

- [Converge](#converge)
    - [Installation](#installation)
    - [Documentation](#documentation)
    - [Usage](#usage)
    - [Development](#development)
        - [Tools](#tools)
        - [RPC](#rpc)
        - [Continuous Integration and Testing](#continuous-integration-and-testing)
    - [License](#license)

<!-- markdown-toc end -->

## Installation

The `` script will download and install the converge binary
to your `/usr/local/bin/` directory:

sudo ./ -v 0.4.0

The same installation script is available at ``:

curl | sudo bash -

You can also use `go get`:

go get

or download a release for your platform from the
[releases page on Github](

## Documentation

Comprehensive documentation can be found at [](

You can learn more about Converge from the following blog posts and presentations:

- [Introducing Converge](
- [Conditionals In Converge](
- [Converge Presentation to STL DevOps](

## Usage

Converge uses [HCL]( for syntax. HCL is a
superset of JSON that looks (and acts) quite a bit nicer.

The basic unit of composition in converge is the module. Modules have parameters
and contain resources. Creating a module looks something like this:

# write "hello world" to disk
param "message" {
  default = "Hello, World in {{param `filename`}}"

param "filename" {
  default = "test.txt"

file.content "render" {
  destination = "{{param `filename`}}"
  content     = "{{param `message`}}"

Invoke this with `converge apply --local samples/fileContent.hcl` to place
a test file on your system. You can also `converge plan --local
samples/fileContent.hcl` to see what changes will be made before you apply them.

## Development

### Tools

For linting, you'll need:

tool | `go get`
---- | --------
 `golint` |
`go tool vet` | (built in)
`gosimple` |
`unconvert` |
`structcheck` |
`varcheck` |
`aligncheck` |
`gas` |

### RPC

You'll need:

- [Google's protobuf compiler](, 3.0
  or above.
- The go protoc plugin: `go get -a`
- The grpc gateway plugin(s): `go get -u`

### Continuous Integration and Testing

We use Wercker for CI with a custom base image. The Dockerfile for that image
can be found at `/ci/Dockerfile` in the root of the project, and is pushed as
`asteris/converge-ci`. You can test Converge in the container with the
following invocation:

docker run -i \
           -t \
           --rm \
           --volume $(pwd):/go/src/ \
           asteris/converge-ci \
           /bin/bash -c 'cd /go/src/; make test'

Benchmarks are run with `make bench`, and fuzzing is run with `make

## License

Converge is licensed under the Apache 2.0 license. See [LICENSE](LICENSE) for
full details.