Bump version to 0.2.5
[snf-image-creator] / docs / install.rst
1 Installation
2 ^^^^^^^^^^^^
3
4 This guide describes how to install snf-image-creator on a Linux system. It is
5 highly recommended to have virtualization capable hardware. snf-image-creator
6 will work on processors that do not support virtualization but it will be slow.
7
8 Dependencies
9 ============
10
11 snf-image-creator depends on the following programs:
12
13  * Python 2 [http://www.python.org/]
14  * Python setuptools [http://pypi.python.org/pypi/setuptools]
15  * Python Dialog [http://pythondialog.sourceforge.net/]
16  * Python bindings for libguestfs [http://libguestfs.org/]
17  * Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]
18  * pyparted [https://fedorahosted.org/pyparted/]
19  * rsync [http://rsync.samba.org/]
20  * ./kamaki [https://code.grnet.gr/projects/kamaki]
21  * Python sh (previously pbs) [https://github.com/amoffat/sh]
22  * ANSI colors for Python [http://pypi.python.org/pypi/ansicolors]
23  * progress [http://pypi.python.org/pypi/progress]
24
25 The above dependencies are resolved differently, depending on the installation
26 method you choose. There are two installation methods available:
27
28 #. `Installation using packages <#install-snf-image-creator-using-packages>`_
29
30 #. `Installation from source <#install-snf-image-creator-from-source>`_
31
32 Install snf-image-creator using packages
33 ========================================
34
35 Ubuntu
36 ------
37
38 For *Ubuntu 12.04 LTS* and *12.10* systems, you can use our official packages
39 found in *grnet/synnefo* Lauchpad PPA.
40
41 Add the synnefo PPA in your system:
42
43 .. code-block:: console
44
45    $ sudo apt-add-repository ppa:grnet/synnefo
46    $ sudo apt-get update
47
48 If *apt-add-repository* is missing, first install:
49
50 *software-properties-common* (Ubuntu 12.10):
51
52 .. code-block:: console
53
54    $ sudo apt-get install software-properties-common
55
56 Or *python-software-properties* (Ubuntu 12.04):
57
58 .. code-block:: console
59
60    $ sudo apt-get install python-software-properties
61
62 After the synnefo repository is set up, you should be able to list
63 snf-image-creator by calling:
64
65 .. code-block:: console
66
67    $ apt-cache showpkg snf-image-creator
68
69 Install the package by issuing:
70
71 .. code-block:: console
72
73    $ sudo apt-get install snf-image-creator
74
75 .. note::
76    If you are asked during the installation to create/update a
77    "supermin appliance", choose "Yes".
78
79 .. warning::
80    In *Ubuntu 12.10* the current package of libguestfs (1.18-2) is broken. Take
81    a look at the open `bug report <https://bugs.launchpad.net/ubuntu/quantal/+source/libguestfs/+bug/1086974>`_.
82    Until version 1.18-2ubunut1 is out, you may workaround this problem by
83    creating a symlink like this:
84
85    *sudo ln -s /usr/lib/guestfs /usr/lib/x86_64-linux-gnu/guestfs*
86
87 Fedora
88 ------
89
90 For *Fedora 17* you can use our official packages hosted at the *synnefo*
91 repository of the openSUSE Build Service.
92
93 Add the *synnefo* repository for *Fedora 17* to *yum*:
94
95 .. code-block:: console
96
97    $ cd /etc/yum.repos.d
98    $ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/Fedora_17/home:GRNET:synnefo.repo
99
100 To list the *snf-image-creator* package use the following command:
101
102 .. code-block:: console
103
104    $ yum info snf-image-creator
105
106 Install the package by issuing:
107
108 .. code-block:: console
109
110    $ yum install snf-image-creator
111
112 CentOS
113 ------
114
115 For *CentOS 6* you can use our official packages hosted at the *synnefo*
116 repository of the openSUSE Build Service.
117
118 Add the *synnefo* repository for *CentOS 6* to the yum repositories list:
119
120 .. code-block:: console
121
122    $ cd /etc/yum.repos.d
123    $ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/CentOS_CentOS-6/home:GRNET:synnefo.repo
124
125 Check the `Fedora <#fedora>`_ instructions on how to install the software.
126
127 Arch Linux
128 ----------
129
130 For *Arch Linux* there are **unofficial** packages in AUR:
131 https://aur.archlinux.org/packages/snf-image-creator/ kindly provided by
132 Axilleas Pipinellis <axilleas@archlinux.info>.
133
134 .. note::
135     Those packages are not maintained by the Synnefo development team.
136
137     Please direct package-specific questions to Axilleas Pipinellis <axilleas@archlinux.info>,
138     Cc: the Synnefo development team <synnefo-devel@googlegroups.com>
139
140 To install the package you may use *yaourt*. Create and install
141 the *yaourt* package:
142
143 .. code-block:: console
144
145    $ wget https://aur.archlinux.org/packages/pa/package-query/package-query.tar.gz
146    $ tar -xvf package-query.tar.gz
147    $ cd package-query
148    $ makepkg -s
149    $ pacman -U package-query-<VERSION>-<ARCH>.pkg.tar.xz
150    $ cd ..
151    $ wget https://aur.archlinux.org/packages/ya/yaourt/yaourt.tar.gz
152    $ tar -xvf yaourt.tar.gz
153    $ cd yaourt
154    $ makepkg -s
155    $ pacman -U yaourt-<VERSION>-<ARCH>.pkg.tar.xz
156
157 Install *snf-image-creator* using yaourt:
158
159 .. code-block:: console
160
161    $ yaourt -Sa snf-image-creator
162
163 Install snf-image-creator from source
164 =====================================
165
166 Manually install the following dependencies:
167
168  * Python 2 [http://www.python.org/]
169  * Python setuptools [http://pypi.python.org/pypi/setuptools]
170  * Python Dialog [http://pythondialog.sourceforge.net/]
171  * Python bindings for libguestfs [http://libguestfs.org/]
172  * Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]
173  * pyparted [https://fedorahosted.org/pyparted/]
174  * rsync [http://rsync.samba.org/]
175
176 In Ubuntu you can do this using:
177  
178 .. code-block:: console
179
180    $ sudo apt-get install python-setuptools python-guestfs python-dialog \
181      python-sendfile python-parted rsync
182
183 If you are using Ubuntu 12.10 you also need to install libguestfs-tools:
184
185 .. code-block:: console
186
187    $ sudo apt-get install libguestfs-tools
188
189 .. note::
190    If you are asked during the installation to create/update a
191    "supermin appliance", choose "Yes".
192
193 Python Virtual Environment
194 --------------------------
195
196 Since snf-image-creator and the rest of its dependencies won't be installed
197 using packages, it's better to work in an isolated python virtual environment
198 (virtualenv).
199
200 Install the Virtual Python Environment builder:
201 http://pypi.python.org/pypi/virtualenv.
202
203 For Ubuntu use the following command:
204
205 .. code-block:: console
206
207    $ sudo apt-get install python-virtualenv
208
209 Then create a new python virtual environment:
210
211 .. code-block:: console
212
213    $ virtualenv --system-site-packages ~/image-creator-env
214
215 and activate it by executing:
216
217 .. code-block:: console
218
219    $ source ~/image-creator-env/bin/activate
220
221 You may later deactivate it using:
222
223 .. code-block:: console
224
225    $ deactivate
226
227 kamaki Installation
228 -------------------
229
230 Refer to `./kamaki documentation <http://docs.dev.grnet.gr/kamaki/latest/installation.html>`_
231 for instructions. You may install kamaki from source inside the virtualenv
232 you've created above or by using binary packages if they are available for your
233 distribution.
234
235 snf-image-creator Installation
236 ------------------------------
237
238 Download the latest snf-image-creator source package from
239 `here <https://code.grnet.gr/projects/snf-image-creator/files>`_ and install it
240 inside the virtualenv using the following commands:
241
242 .. code-block:: console
243
244    $ tar -xf snf_image_creator-<VERSION>.tar.gz
245    $ cd snf_image_creator-<VERSION>
246    $ python ./setup.py install
247
248 Alternatively, you can install the bleeding edge version of the software by
249 cloning its git repository:
250
251 .. code-block:: console
252
253    $ git clone https://code.grnet.gr/git/snf-image-creator
254    $ cd snf-image-creator
255    $ python ./setup.py install
256
257 To do the latter, you'll need to have git (http://git-scm.com/) installed.
258 For ubuntu this can be done using:
259
260 .. code-block:: console
261
262    $ sudo apt-get install git
263
264 .. warning::
265    Keep in mind that the bleeding edge version may be unstable or even
266    unusable.
267