About LEAP command line interface
=================================

This gem installs an executable 'leap' that allows you to manage servers using the leap platform.

Installation
=================================

Prerequisites:

    sudo apt-get install ruby ruby-dev rsync openssh-client

To install leap command system-wide:

    sudo gem install leap_cli

To install without root privileges:

    gem install leap_cli --user-install

To run from a clone of the git repo, see "Development", below.

Usage
=================================

Run `leap help` for a usage instructions.

Here is an example usage:

    leap new-provider provider
    cd provider
    edit configuration files (see below)
    leap compile

Directories and Files
=================================

The general structure of leap project looks like this:

    my_leap_project/                 # your project directory
      leap_platform/                 # a clone of the leap_platform puppet recipes
      provider/                      # your provider-specific configurations

The "leap" command should be run from within the "provider" directory.

Within the "provider" directory:

    nodes/               # one configuration file per node (i.e. server)
    services/            # nodes inherit from these files if specified in node config.
    tags/                # nodes inherit from these files if specified in node config.
    files/               # text and binary files needed for services and nodes, including keypairs
    users/               # crypto key material for sysadmins
    common.yaml          # all nodes inherit these options
    provider.yaml        # global service provider definition

Configuration Files
=================================

All configuration files are in JSON format. For example

    {
      "key1": "value1",
      "key2": "value2"
    }

Keys should match /[a-z0-9_]/

Unlike traditional JSON, comments are allowed. If the first non-whitespace character is '#' the line is treated as a comment.

    # this is a comment
    {
      # this is a comment
      "key": "value"  # this is an error
    }

Options in the configuration files might be nested. For example:

    {
      "openvpn": {
        "ip_address": "1.1.1.1"
      }
    }

If the value string is prefixed with an '=' character, the value is evaluated as ruby. For example

    {
      "domain": {
        "public": "domain.org"
      }
      "api_domain": "= 'api.' + domain.public"
    }

In this case, "api_domain" will be set to "api.domain.org".

The following methods are available to the evaluated ruby:

* nodes -- A list of all nodes. This list can be filtered.

* global.services -- A list of all services.

* global.tags -- A list of all tags.

* file(file_path) -- Inserts the full contents of the file. If the file is an erb
  template, it is rendered. The file is searched for by first checking platform
  and then provider/files,

* variable -- Any variable inherited by a particular node is available
  by just referencing it using either hash notation or object notation
  (i.e. self['domain']['public'] or domain.public). Circular
  references are not allowed, but otherwise it is ok to nest
  evaluated values in other evaluated values.


Node Configuration
=================================

The name of the file will be the hostname of the node.

An example configuration "nodes/dns-europe.json"

    {
       "services": "dns",
       "tags": ["production", "europe"],
       "ip_address": "1.1.1.1"
    }

This node will have hostname "dns-europe" and it will inherit from the following files (in this order):

    common.json
    services/dns.json
    tags/europe.json
    tags/production.json

Development
=================================

How to set up your environment for developing the ``leap`` command.

Prerequisites
---------------------------------

Debian Squeeze

    sudo apt-get install git ruby ruby-dev rubygems
    sudo gem install bundler rake
    export PATH=$PATH:/var/lib/gems/1.8/bin

Debian Wheezy

    sudo apt-get install git ruby ruby-dev bundler

Ubuntu

    sudo apt-get install git ruby ruby-dev
    sudo gem install bundler

Install from git
--------------------------------------

Download the source and install the required gems:

    git clone git://leap.se/leap_cli      # clone leap_cli code
    cd leap_cli
    bundle                                # install required gems

Running from the source directory
--------------------------------------

To run the ``leap`` command directly from the source tree, symlink bin/leap
into your path:

    cd leap_cli
    ln -s `pwd`/bin/leap ~/bin    # link executable somewhere in your bin path
    which leap                    # make sure you will run leap_cli/bin/leap
    leap help

If you get an error, make sure to check ``which leap``. Some versions of ``bundle`` will
incorrectly install a broken ``leap`` command in the gem bin directory when you do ``bundle``.

Why not use ``bundle exec leap`` to run the command? This works, so long as your current
working directory is under leap_cli. Because the point is to be able to run ``leap`` in
other places, it is easier to create the symlink. If you run ``leap`` directly, and not via
the command launcher that rubygems installs, leap will run in a mode that simulates
``bundle exec leap`` (i.e. only gems included in Gemfile are allow to be loaded).

Running as a gem
--------------------------------------

To install ``leap`` as a gem, do this:

    cd leap_cli
    rake build
    rake install

And then make sure your PATH is set to include where leap is installed.
It should warn you if this is not the case.