diff options
| -rw-r--r-- | README.md | 163 |
1 files changed, 33 insertions, 130 deletions
@@ -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). |