platform development spelling
[leap_doc.git] / docs / platform / details / development.md
1 @title = "Development Environment"
2 @summary = "Setting up an environment for modifying the leap_platform."
3 @toc = true
4
5 If you are wanting to make local changes to your provider, or want to contribute some fixes back to LEAP, we recommend that you follow this guide to build up a development environment to test your changes first. Using this method, you can quickly test your changes without deploying them to your production environment, while benefitting from the convenience of reverting to known good states in order to retry things from scratch.
6
7 This page will walk you through setting up nodes using [Vagrant](http://www.vagrantup.com/) for convenient deployment testing, snapshotting known good states, and reverting to previous snapshots.
8
9 Requirements
10 ============
11
12 * A real machine with virtualization support in the CPU (VT-x or AMD-V). In other words, not a virtual machine.
13 * Have at least 4gb of RAM.
14 * Have a fast internet connection (because you will be downloading a lot of big files, like virtual machine images).
15 * You should do everything described below as an unprivileged user, and only run those commands as root that are noted with *sudo* in front of them. Other than those commands, there is no need for privileged access to your machine, and in fact things may not work correctly.
16
17 Install prerequisites
18 --------------------------------
19
20 For development purposes, you will need everything that you need for deploying the LEAP platform:
21
22 * LEAP cli
23 * A provider instance
24
25 You will also need to setup a virtualized Vagrant environment, to do so please make sure you have the following
26 pre-requisites installed:
27
28 *Debian & Ubuntu*
29
30 Install core prerequisites:
31
32     sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make
33
34 Install Vagrant in order to be able to test with local virtual machines (typically optional, but required for this tutorial). You probably want a more recent version directly from [vagrant.](https://www.vagrantup.com/downloads.htm)
35
36     sudo apt-get install vagrant virtualbox
37
38
39 *Mac OS X 10.9 (Mavericks)*
40
41 Install Homebrew package manager from http://brew.sh/ and enable the [System Duplicates Repository](https://github.com/Homebrew/homebrew/wiki/Interesting-Taps-&-Branches) (needed to update old software versions delivered by Apple) with
42
43     brew tap homebrew/dupes
44
45 Update OpenSSH to support ECDSA keys. Follow [this guide](http://www.dctrwatson.com/2013/07/how-to-update-openssh-on-mac-os-x/) to let your system use the Homebrew binary.
46
47     brew install openssh --with-brewed-openssl --with-keychain-support
48
49 The certtool provided by Apple it's really old, install the one provided by GnuTLS and shadow the system's default.
50
51     sudo brew install gnutls
52     ln -sf /usr/local/bin/gnutls-certtool /usr/local/bin/certool
53
54 Install the Vagrant and VirtualBox packages for OS X from their respective Download pages.
55
56 * http://www.vagrantup.com/downloads.html
57 * https://www.virtualbox.org/wiki/Downloads
58
59
60 2. Install
61
62
63 Adding development nodes to your provider
64 =========================================
65
66 Now you will add local-only Vagrant development nodes to your provider.
67
68 You do not need to setup a different provider instance for development, in fact it is more convenient if you do not, but you can if you wish.  If you do not have a provider already, you will need to create one and configure it before continuing (it is recommended you go through the [Quick Start](quick-start) before continuing down this path).
69
70
71 Create local development nodes
72 ------------------------------
73
74 We will add "local" nodes, which are special nodes that are used only for testing. These nodes exist only as virtual machines on your computer, and cannot be accessed from the outside. Each "node" is a server that can have one or more services attached to it. We recommend that you create different nodes for different services to better isolate issues.
75
76 While in your provider directory, create a local node, with the service "webapp":
77
78     $ leap node add --local web1 services:webapp
79      = created nodes/web1.json
80      = created files/nodes/web1/
81      = created files/nodes/web1/web1.key
82      = created files/nodes/web1/web1.crt
83
84 This command creates a node configuration file in `nodes/web1.json` with the webapp service.
85
86 Starting local development nodes
87 --------------------------------
88
89 In order to test the node "web1" we need to start it. Starting a node for the first time will spin up a virtual machine. The first time you do this will take some time because it will need to download a VM image (about 700mb). After you've downloaded the base image, you will not need to download it again, and instead you will re-use the downloaded image (until you need to update the image).
90
91 NOTE: Many people have difficulties getting Vagrant working. If the following commands do not work, please see the Vagrant section below to troubleshoot your Vagrant install before proceeding.
92
93     $ leap local start web1
94      = created test/
95      = created test/Vagrantfile
96      = installing vagrant plugin 'sahara'
97     Bringing machine 'web1' up with 'virtualbox' provider...
98     [web1] Box 'leap-wheezy' was not found. Fetching box from specified URL for
99     the provider 'virtualbox'. Note that if the URL does not have
100     a box for this provider, you should interrupt Vagrant now and add
101     the box yourself. Otherwise Vagrant will attempt to download the
102     full box prior to discovering this error.
103     Downloading or copying the box...
104     Progress: 3% (Rate: 560k/s, Estimated time remaining: 0:13:36)
105     ...
106     Bringing machine 'web1' up with 'virtualbox' provider...
107     [web1] Importing base box 'leap-wheezy'...
108     0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
109
110 Now the virtual machine 'web1' is running. You can add another local node using the same process. For example, the webapp node needs a databasse to run, so let's add a "couchdb" node:
111
112     $ leap node add --local db1 services:couchdb
113     $ leap local start
114      = updated test/Vagrantfile
115     Bringing machine 'db1' up with 'virtualbox' provider...
116     [db1] Importing base box 'leap-wheezy'...
117     [db1] Matching MAC address for NAT networking...
118     [db1] Setting the name of the VM...
119     [db1] Clearing any previously set forwarded ports...
120     [db1] Fixed port collision for 22 => 2222. Now on port 2202.
121     [db1] Creating shared folders metadata...
122     [db1] Clearing any previously set network interfaces...
123     [db1] Preparing network interfaces based on configuration...
124     [db1] Forwarding ports...
125     [db1] -- 22 => 2202 (adapter 1)
126     [db1] Running any VM customizations...
127     [db1] Booting VM...
128     [db1] Waiting for VM to boot. This can take a few minutes.
129     [db1] VM booted and ready for use!
130     [db1] Configuring and enabling network interfaces...
131     [db1] Mounting shared folders...
132     [db1] -- /vagrant
133
134 You now can follow the normal LEAP process and initialize it and then deploy your recipes to it:
135
136     $ leap node init web1
137     $ leap deploy web1
138     $ leap node init db1
139     $ leap deploy db1
140
141
142 Useful local development commands
143 =================================
144
145 There are many useful things you can do with a virtualized development environment.
146
147 Listing what machines are running
148 ---------------------------------
149
150 Now you have the two virtual machines "web1" and "db1" running, you can see the running machines as follows:
151
152     $ leap local status
153     Current machine states:
154
155     db1                      running (virtualbox)
156     web1                     running (virtualbox)
157
158     This environment represents multiple VMs. The VMs are all listed
159     above with their current state. For more information about a specific
160     VM, run `vagrant status NAME`.
161
162 Stopping machines
163 -----------------
164
165 It is not recommended that you leave your virtual machines running when you are not using them. They consume memory and other resources! To stop your machines, simply do the following:
166
167     $ leap local stop web1 db1
168
169 Connecting to machines
170 ----------------------
171
172 You can connect to your local nodes just like you do with normal LEAP nodes, by running 'leap ssh node'.
173
174 However, if you cannot connect to your local node, because the networking is not setup properly, or you have deployed a firewall that locks you out, you may need to access the graphical console.
175
176 In order to do that, you will need to configure Vagrant to launch a graphical console and then you can login as root there to diagnose the networking problem. To do this, add the following to your $HOME/.leaprc:
177
178     @custom_vagrant_vm_line = 'config.vm.provider "virtualbox" do |v|
179       v.gui = true
180     end'
181
182 and then start, or restart, your local Vagrant node. You should get a VirtualBox graphical interface presented to you showing you the bootup and eventually the login.
183
184 Snapshotting machines
185 ---------------------
186
187 A very useful feature of local Vagrant development nodes is the ability to snapshot the current state and then revert to that when you need.
188
189 For example, perhaps the base image is a little bit out of date and you want to get the packages updated to the latest before continuing. You can do that simply by starting the node, connecting to it and updating the packages and then snapshotting the node:
190
191     $ leap local start web1
192     $ leap ssh web1
193     web1# apt-get -u dist-upgrade
194     web1# exit
195     $ leap local save web1
196
197 Now you can deploy to web1 and if you decide you want to revert to the state before deployment, you simply have to reset the node to your previous save:
198
199     $ leap local reset web1
200
201 More information
202 ----------------
203
204 See `leap help local` for a complete list of local-only commands and how they can be used.
205
206
207 Limitations
208 ===========
209
210 Please consult the known issues for vagrant, see the [Known Issues](known-issues), section *Special Environments*
211
212
213 Other useful plugins
214 ====================
215
216 . The vagrant-cachier (plugin http://fgrehm.viewdocs.io/vagrant-cachier/) lets you cache .deb packages on your hosts so they are not downloaded by multiple machines over and over again, after resetting to a previous state.
217
218 Troubleshooting Vagrant
219 =======================
220
221 To troubleshoot vagrant issues, try going through these steps:
222
223 * Try plain vagrant using the [Getting started guide](http://docs.vagrantup.com/v2/getting-started/index.html).
224 * If that fails, make sure that you can run virtual machines (VMs) in plain virtualbox (Virtualbox GUI or VBoxHeadless).
225   We don't suggest a sepecial howto for that, [this one](http://www.thegeekstuff.com/2012/02/virtualbox-install-create-vm/) seems pretty decent, or you follow the [Oracale Virtualbox User Manual](http://www.virtualbox.org/manual/UserManual.html). There's also specific documentation for [Debian](https://wiki.debian.org/VirtualBox) and for [Ubuntu](https://help.ubuntu.com/community/VirtualBox). If you succeeded, try again if you now can start vagrant nodes using plain vagrant (see first step).
226 * If plain vagrant works for you, you're very close to using vagrant with leap ! If you encounter any problems now, please [contact us](https://leap.se/en/about-us/contact) or use our [issue tracker](https://leap.se/code)
227
228 Known working combinations
229 --------------------------
230
231 Please consider that using other combinations might work for you as well, these are just the combinations we tried and worked for us:
232
233
234 Debian Wheezy
235 -------------
236
237 * `virtualbox-4.2 4.2.16-86992~Debian~wheezy` from Oracle and `vagrant 1.2.2` from vagrantup.com
238
239
240 Ubuntu Raring 13.04
241 -------------------
242
243 * `virtualbox 4.2.10-dfsg-0ubuntu2.1` from Ubuntu raring and `vagrant 1.2.2` from vagrantup.com
244
245 Mac OS X 10.9
246 -------------
247
248 * `VirtualBox 4.3.10` from virtualbox.org and `vagrant 1.5.4` from vagrantup.com
249
250
251 Using Vagrant with libvirt/kvm
252 ==============================
253
254 Vagrant can be used with different providers/backends, one of them is [vagrant-libvirt](https://github.com/pradels/vagrant-libvirt). Here are the steps how to use it. Be sure to use a recent vagrant version for the vagrant-libvirt plugin (>= 1.5, which can only be fetched from http://www.vagrantup.com/downloads.html at this moment).
255
256 Install vagrant-libvirt plugin and add box
257 ------------------------------------------
258     sudo apt-get install libvirt-bin libvirt-dev
259     # you need to assign the new 'libvirtd' group to your user in a running x session, or logout and login again:
260     newgrp libvirtd
261     # to build the vagrant-libvirt plugin you need the following packages:
262     sudo apt-get install ruby-dev libxslt-dev libxml2-dev libvirt-dev
263     vagrant plugin install vagrant-libvirt
264     vagrant plugin install sahara
265     vagrant box add leap-wheezy https://downloads.leap.se/platform/vagrant/libvirt/leap-wheezy.box --provider libvirt
266
267 Remove Virtualbox
268 -----------------
269     sudo apt-get remove virtualbox*
270
271 Debugging
272 ---------
273
274 If you get an error in any of the above commands, try to get some debugging information, it will often tell you what is wrong. In order to get debugging logs, you simply need to re-run the command that produced the error but prepend the command with VAGRANT_LOG=info, for example:
275     VAGRANT_LOG=info vagrant box add leap-wheezy https://downloads.leap.se/platform/vagrant/libvirt/leap-wheezy.box
276
277 Start it
278 --------
279
280 Use this example Vagrantfile:
281
282     Vagrant.configure("2") do |config|
283       config.vm.define :testvm do |testvm|
284         testvm.vm.box = "leap-wheezy"
285         testvm.vm.network :private_network, :ip => '10.6.6.201'
286       end
287
288       config.vm.provider :libvirt do |libvirt|
289         libvirt.connect_via_ssh = false
290       end
291     end
292
293 Then:
294
295     vagrant up --provider=libvirt
296
297 If everything works, you should export libvirt as the VAGRANT_DEFAULT_PROVIDER:
298
299     export VAGRANT_DEFAULT_PROVIDER="libvirt"
300
301 Now you should be able to use the `leap local` commands.
302
303 Known Issues
304 ------------
305
306 * 'Call to virConnectOpen failed: internal error: Unable to locate libvirtd daemon in /usr/sbin (to override, set $LIBVIRTD_PATH to the name of the libvirtd binary)' - you don't have the libvirtd daemon running or installed, be sure you installed the 'libvirt-bin' package and it is running
307 * 'Call to virConnectOpen failed: Failed to connect socket to '/var/run/libvirt/libvirt-sock': Permission denied' - you need to be in the libvirt group to access the socket, do 'sudo adduser <user> libvirt' and then re-login to your session
308 * if each call to vagrant ends up with a segfault, it may be because you still have virtualbox around. if so, remove virtualbox to keep only libvirt + KVM. according to https://github.com/pradels/vagrant-libvirt/issues/75 having two virtualization engines installed simultaneously can lead to such weird issues.
309 * see the [vagrant-libvirt issue list on github](https://github.com/pradels/vagrant-libvirt/issues)
310 * be sure to use vagrant-libvirt >= 0.0.11 and sahara >= 0.0.16 (which are the latest stable gems you would get with `vagrant plugin install [vagrant-libvirt|sahara]`) for proper libvirt support
311 * for shared folder support, you need nfs-kernel-server installed on the host machine and set up sudo to allow unpriviledged users to modify /etc/exports. See [vagrant-libvirt#synced-folders](https://github.com/pradels/vagrant-libvirt#synced-folders)
312
313
314     sudo apt-get install nfs-kernel-server