Use master branches for platform on CI
[leap_cli.git] / README.md
1 About LEAP command line interface
2 ===================================================
3
4 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/docs).
5
6 Installation
7 ===================================================
8
9 Install prerequisites:
10
11     sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake gcc make zlib1g-dev
12
13 NOTE: leap_cli requires ruby 1.9 or later.
14
15 Optionally install Vagrant in order to be able to test with local virtual machines (recommended):
16
17     sudo apt-get install vagrant virtualbox zlib1g-dev
18
19 Install the `leap` command system-wide:
20
21     sudo gem install leap_cli
22
23 Alternately, you can install just for your user:
24
25     gem install --user-install leap_cli
26     [ $(which ruby) ] && PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"
27
28 The `--user-install` option for `gem` will install gems to a location in your home directory (handy!) but this directory is not in your PATH (not handy!). Add the second line to your `.bashrc` file so that all your shells will have `leap` in PATH.
29
30 For other methods of installing `leap_cli`, see below.
31
32 Usage
33 ===================================================
34
35 * Run `leap help` for a help with commands.
36 * Visit https://leap.se/docs/platform for tutorials and detailed documentation.
37
38 Development
39 ===================================================
40
41 How to set up your environment for developing the ``leap`` command.
42
43 Prerequisites
44 ---------------------------------------------------
45
46 Debian & Ubuntu
47
48     sudo apt-get install git ruby ruby-dev rake bundler
49
50 Install from git
51 ---------------------------------------------------
52
53 Download the source:
54
55     cd leap_cli
56
57 Installing from the source
58 ---------------------------------------------------
59
60 Build the gem:
61
62     git clone https://leap.se/git/leap_cli.git
63     cd leap_cli
64     rake build
65
66 Install as root user:
67
68     sudo rake install
69
70 Alternately, install as unprivileged user:
71
72     rake install
73     PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"
74
75 Running directly from the source directory
76 ---------------------------------------------------
77
78 To run the ``leap`` command directly from the source tree, you need to install
79 the required gems using ``bundle`` and symlink ``bin/leap`` into your path:
80
81     git clone https://leap.se/git/leap_cli.git
82     cd leap_cli
83     bundle                        # install required gems
84     ln -s `pwd`/bin/leap ~/bin    # link executable somewhere in your bin path
85     which leap                    # make sure you will run leap_cli/bin/leap
86     leap help
87
88 If you get an error, make sure to check ``which leap``. Some versions of ``bundle`` will
89 incorrectly install a broken ``leap`` command in the gem bin directory when you do ``bundle``.
90
91 Why not use ``bundle exec leap`` to run the command? This works, so long as your current
92 working directory is under leap_cli. Because the point is to be able to run ``leap`` in
93 other places, it is easier to create the symlink. If you run ``leap`` directly, and not via
94 the command launcher that rubygems installs, leap will run in a mode that simulates
95 ``bundle exec leap`` (i.e. only gems included in Gemfile are allowed to be loaded).