Correct typos in installation doc
[snf-image-creator] / docs / install.rst
1 Installation
2 ^^^^^^^^^^^^
3
4 This guide describes how to install snf-image-creator on an Ubuntu 12.04 LTS
5 system. It is highly recommended to have virtualization capable hardware.
6 snf-image-creator will work on processors that do not support virtualization
7 but it will be extremely slow.
8
9 Dependencies
10 ============
11
12 snf-image-creator depends on the following programs:
13
14  * Python 2 [http://www.python.org/]
15  * Python setuptools [http://pypi.python.org/pypi/setuptools]
16  * Python Dialog [http://pythondialog.sourceforge.net/]
17  * Python bindings for libguestfs [http://libguestfs.org/]
18  * Kamaki [https://code.grnet.gr/projects/kamaki]
19  * Python sh (previously pbs) [https://github.com/amoffat/sh]
20  * ANSI colors for Python [http://pypi.python.org/pypi/ansicolors]
21  * progress [http://pypi.python.org/pypi/progress]
22  * Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]
23
24 The above dependencies are resolved differently, depending on the installation
25 method you choose.
26
27 There are two installation methods. The first uses official packages whereas
28 the second installs snf-image-creator and its dependencies from source. Both
29 methods are presented below.
30
31 Install snf-image-creator using official packages
32 =================================================
33
34 This method of installing snf-image-creator has all the advantages of Ubuntu's
35 APT installation:
36
37 * Automatic resolution of dependencies
38 * Simple installation of consequent updates
39
40 In order to proceed with the installation, you must first add GRNET's dev repo
41 to your sources. You can use the following commands:
42
43 .. code-block:: console
44
45    cd /etc/apt/sources.list.d
46    echo "deb http://apt.dev.grnet.gr precise main" | \
47    sudo tee -a  apt.dev.grnet.gr.list
48    echo "deb-src http://apt.dev.grnet.gr precise main" | \
49    sudo tee -a apt.dev.grnet.gr.list
50
51 You will also need to import the repo's GPG key. You can use the ``curl`` tool
52 for this.
53
54 .. code-block:: console
55
56    $ sudo apt-get install curl
57
58 Use the following command to import the GPG key:
59
60 .. code-block:: console
61
62    $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub | sudo apt-key add -
63
64 You can verify that the repo has been added successfully if snf-image-creator
65 exists as a package. First do an update of your sources:
66
67 .. code-block:: console
68
69    $ sudo apt-get update
70
71 then check if snf-image-creator exists with the following command:
72
73 .. code-block:: console
74
75    $ apt-cache showpkg snf-image-creator
76
77 If GRNET's dev repo has been added successfully, you can install
78 snf-image-creator, along with its dependencies, with the following command:
79
80 .. code-block:: console
81
82    $ sudo apt-get install snf-image-creator
83
84 The installation might take a while. Please note that at some point during the
85 installation you will be prompted to create/update a "supermin appliance". This
86 is a setting regarding libguestfs and you can safely choose "Yes".
87
88 Install snf-image-creator from source
89 =====================================
90
91 This method provides you with the cutting edge of snf-image-creator, which
92 gives you access to all the latest features. Keep in mind, however,
93 that you may experience instability issues.
94
95 The first four dependencies (python2, setuptools, Python-Dialog, and
96 libguestfs) need to be installed manually by the user. In an Ubuntu 12.04 LTS
97 system this can be achieved by installing packages provided by the
98 distribution, using the following command:
99
100 .. code-block:: console
101
102    $ apt-get install python-setuptools python-guestfs python-dialog
103
104 The rest of the dependencies will be automatically resolved by setuptools.
105 Note that at some point during the installation, you will be prompted to
106 create/update a "supermin appliance". This is a setting regarding libguestfs
107 and you can safely choose "Yes".
108
109 In order to download the source files, git needs to be installed. You can do
110 so with the following command:
111
112 .. code-block:: console
113
114    $ apt-get install git
115
116 Python Virtual Environment
117 --------------------------
118
119 Since snf-image-creator and the rest of its dependencies won't be installed
120 using packages, it's better to work in an isolated python virtual environment
121 (virtualenv). Installing the Virtual Python Environment builder in Ubuntu can
122 be accomplished using the following command:
123
124 .. code-block:: console
125
126    $ apt-get install python-virtualenv
127
128 Now, create a new python virtual environment like this:
129
130 .. code-block:: console
131
132    $ virtualenv --system-site-packages ~/image-creator-env
133
134 and activate it by executing:
135
136 .. code-block:: console
137
138    $ source ~/image-creator-env/bin/activate
139
140 You can later deactivate it using the following command:
141
142 .. code-block:: console
143
144    $ deactivate
145
146 snf-common Installation
147 -----------------------
148
149 Install snf-common from source, by cloning it's repository:
150
151 .. code-block:: console
152
153    $ cd ~
154    $ git clone https://code.grnet.gr/git/synnefo
155    $ cd synnefo/snf-common
156    $ python setup.py build
157
158 Then, make sure you are within the activated virtual environment before you
159 execute:
160
161 .. code-block:: console
162
163    $ python setup.py install
164
165 kamaki Installation
166 -------------------
167
168 Install kamaki from source, by cloning it's repository:
169
170 .. code-block:: console
171
172    $ cd ~
173    $ git clone https://code.grnet.gr/git/kamaki
174    $ cd kamaki
175    $ ./setup.py build
176
177 As above, make sure you are within the activated virtual environment before you
178 execute:
179
180 .. code-block:: console
181
182    $ ./setup.py install
183
184 snf-image-creator Installation
185 ------------------------------
186
187 Install snf-image-creator the same way:
188
189 .. code-block:: console
190
191    $ cd ~
192    $ git clone https://code.grnet.gr/git/snf-image-creator
193    $ git checkout stable-0.1
194    $ cd snf-image-creator
195    $ ./setup.py build
196
197 And from within the virtual environment execute:
198
199 .. code-block:: console
200
201    $ ./setup.py install