summaryrefslogtreecommitdiff
path: root/cli/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'cli/README.md')
-rw-r--r--cli/README.md132
1 files changed, 132 insertions, 0 deletions
diff --git a/cli/README.md b/cli/README.md
new file mode 100644
index 0000000..fccd6d1
--- /dev/null
+++ b/cli/README.md
@@ -0,0 +1,132 @@
+About LEAP command line interface
+=================================
+
+This gem installs an executable 'leap' that allows you to manage servers using the leap platform.
+
+Installation
+=================================
+
+To install the gem:
+
+ gem install leap_cli
+
+To run from a clone of the git repo, see "Development", below.
+
+Usage
+=================================
+
+This tool is incomplete, so most commands don't yet work.
+
+Run `leap help` for a usage instructions.
+
+Here is an example usage:
+
+ leap init 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/ # the 'root' 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.
+
+You can name these directories whatever you like. The leap command will walk up the directory tree until it finds a directory that looks like a 'root' 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"
+ }
+ }
+
+When compiled into hiera and made available in puppet, this becomes a Hash object with flattened keys:
+
+ {"openvpn.ip_address" => "1.1.1.1"}
+
+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
+=================================
+
+prerequisites:
+
+* rubygems (``apt-get install rubygems``)
+* bundler (``gem install bundler``)
+
+Install command line ``leap``:
+
+ git clone git://leap.se/leap_cli # clone leap cli code
+ cd leap_cli
+ bundle # install required gems
+ ln -s `pwd`/bin/leap ~/bin # link executable somewhere in your bin path
+
+You can experiment using the example provider in the test directory
+
+ cd test/provider
+ leap
+
+Alternately, you can create your own provider for testing:
+
+ mkdir ~/dev/example.org
+ cd ~/dev/example.org
+ git clone git://leap.se/leap_platform
+ leap init provider
+ cd provider
+ leap
+