aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorelijah <elijah@riseup.net>2013-02-10 11:53:34 -0800
committerelijah <elijah@riseup.net>2013-02-10 11:53:34 -0800
commitd344cc712c85f813eff43737bbb928591fa884d2 (patch)
tree2228589c02af02329c4b04b40d537e90ff54ab0d
parentb8c25277760e209bff866b70e1b1cc996ed2b806 (diff)
downloadleap_cli-d344cc712c85f813eff43737bbb928591fa884d2.tar.gz
leap_cli-d344cc712c85f813eff43737bbb928591fa884d2.tar.bz2
updated readme
-rw-r--r--README.md163
1 files changed, 33 insertions, 130 deletions
diff --git a/README.md b/README.md
index 293515e..75dddfd 100644
--- a/README.md
+++ b/README.md
@@ -1,143 +1,59 @@
About LEAP command line interface
-=================================
+===================================================
-This gem installs an executable 'leap' that allows you to manage servers using the leap platform. You can read about the [platform on-line](https://leap.se).
+This gem installs an executable 'leap' that allows you to manage servers using the LEAP platform. You can read about the [platform on-line](https://leap.se).
Installation
-=================================
+===================================================
-Prerequisites:
+Install prerequisites:
- sudo apt-get install ruby ruby-dev rsync openssh-client
+ sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake
-To install leap command system-wide:
+Optionally install Vagrant in order to be able to test with local virtual machines (recommended):
- 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:
-
- mkdir provider
- cd provider
- leap init --domain example.org .
- leap node add vpn1 --service openvpn
- leap compile
-
-Directories and Files
-=================================
-
-A leap project consistents of two directories:
-
-* provider directory: this is the directory where all your configurations live. By definition, a provider directory contains a file named Leapfile.
-* platform directory: this is the directory where the puppet recipes live. The path to this directory is specified in the Leapfile. Typically, the platform directory will be a clone or branch of git://leap.se/leap_platform.
-
-The "leap" command must always be run under provider directory (or one of its children).
-
-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/ # cryptographic key material for sysadmins
- hiera/ # compile yaml files that contain everything needed to deploy a particular node.
- 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.
+ sudo apt-get install vagrant virtualbox
- # this is a comment
- {
- # this is a comment
- "key": "value" # this is an error
- }
+NOTE: leap_cli should work with ruby1.8, but has only been tested using ruby1.9.
-Options in the configuration files might be nested. For example:
+Install the `leap` command:
- {
- "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.
+ sudo gem install leap_cli
-* global.tags -- A list of all tags.
+Alternately, you can install `leap` from source:
-* file(file_path) -- Inserts the full contents of the file. If the file is an erb
- template, it is rendered.
+ sudo apt-get install rake
+ git clone git://leap.se/leap_cli.git
+ cd leap_cli
+ rake build
-* 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.
+Install as root user (recommended):
+ sudo rake install
-Node Configuration
-=================================
+Install as unprivileged user:
-The name of the file will be the hostname of the node.
+ rake install
+ # watch out for the directory leap is installed to, then i.e.
+ sudo ln -s ~/.gem/ruby/1.9.1/bin/leap /usr/local/bin/leap
-An example configuration "nodes/dns-europe.json"
+With both methods, you can use now /usr/local/bin/leap, which in most cases will be in your $PATH.
- {
- "services": "dns",
- "tags": ["production", "europe"],
- "ip_address": "1.1.1.1"
- }
+To run directly from a clone of the git repo, see "Development", below.
-This node will have hostname "dns-europe" and it will inherit from the following files (in this order):
+Usage
+===================================================
- common.json
- services/dns.json
- tags/europe.json
- tags/production.json
+* Run `leap help` for a help with commands.
+* Visit https://leap.se/docs/platform for tutorials and detailed documentation.
Development
-=================================
+===================================================
How to set up your environment for developing the ``leap`` command.
Prerequisites
----------------------------------
+---------------------------------------------------
Debian Squeeze
@@ -155,27 +71,15 @@ Ubuntu
sudo gem install bundler
Install from git
---------------------------------------
+---------------------------------------------------
Download the source:
- git clone git://leap.se/leap_cli # clone leap_cli code
+ git clone git://leap.se/leap_cli
cd leap_cli
-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.
-
Running from the source directory
---------------------------------------
+---------------------------------------------------
To run the ``leap`` command directly from the source tree, you need to install
the required gems using ``bundle`` and symlink ``bin/leap`` into your path:
@@ -193,5 +97,4 @@ Why not use ``bundle exec leap`` to run the command? This works, so long as your
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).
-
+``bundle exec leap`` (i.e. only gems included in Gemfile are allowed to be loaded).