Update the documentation to reflect v0.2
[snf-image-creator] / docs / install.rst
1 Installation
2 ^^^^^^^^^^^^
3
4 This guide describes how to install snf-image-creator on your machine. 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  * ./kamaki [https://code.grnet.gr/projects/kamaki]
20  * Python sh (previously pbs) [https://github.com/amoffat/sh]
21  * ANSI colors for Python [http://pypi.python.org/pypi/ansicolors]
22  * progress [http://pypi.python.org/pypi/progress]
23
24 The above dependencies are resolved differently, depending on the installation
25 method you choose. There are two installation methods available:
26
27 #. `Installation using official packages <#install-snf-image-creator-using-official-packages>`_ (currently only for Ubuntu 12.04 LTS and 12.10).
28
29 #. `Installation from source <#install-snf-image-creator-using-official-packages>`_
30
31 Install snf-image-creator using official packages
32 =================================================
33
34 For Ubuntu systems, you can use our official packages found in the Lauchpad
35 PPA: *ppa:grnet/synnefo*
36
37 .. note::
38    This method of installing snf-image-creator has all the advantages of
39    Ubuntu's APT installation, like automatic dependencies resolution and simple
40    update process.
41
42 In order to proceed with the installation, you must first add the synnefo PPA
43 repository in your system:
44
45 .. code-block:: console
46
47    $ sudo apt-add-repository ppa:grnet/synnefo
48    $ sudo apt-get update
49
50 If *apt-add-repository* is missing, install *software-properties-common* first:
51
52 .. code-block:: console
53
54    $ sudo apt-get install software-properties-common
55
56 The snf-image-creator package should now be listed calling:
57
58 .. code-block:: console
59
60    $ apt-cache showpkg snf-image-creator
61
62 You can now install the package by issuing:
63
64 .. code-block:: console
65
66    $ sudo apt-get install snf-image-creator
67
68 .. note::
69    If you are asked during the installation to create/update a
70    "supermin appliance", choose "Yes".
71
72 Install snf-image-creator from source
73 =====================================
74
75 Manually install the following dependencies:
76
77  * Python 2 [http://www.python.org/]
78  * Python setuptools [http://pypi.python.org/pypi/setuptools]
79  * Python Dialog [http://pythondialog.sourceforge.net/]
80  * Python bindings for libguestfs [http://libguestfs.org/]
81  * Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]
82  * pyparted [https://fedorahosted.org/pyparted/]
83
84 In Ubuntu you can do this using:
85  
86 .. code-block:: console
87
88    $ apt-get install python-setuptools python-guestfs python-dialog \
89      python-sendfile python-parted
90
91 .. note::
92    If you are asked during the installation to create/update a
93    "supermin appliance", choose "Yes".
94
95 Python Virtual Environment
96 --------------------------
97
98 Since snf-image-creator and the rest of its dependencies won't be installed
99 using packages, it's better to work in an isolated python virtual environment
100 (virtualenv).
101
102 Install the Virtual Python Environment builder:
103 http://pypi.python.org/pypi/virtualenv.
104
105 For Ubuntu use the following command:
106
107 .. code-block:: console
108
109    $ apt-get install python-virtualenv
110
111 Create a new python virtual environment:
112
113 .. code-block:: console
114
115    $ virtualenv --system-site-packages ~/image-creator-env
116
117 and activate it by executing:
118
119 .. code-block:: console
120
121    $ source ~/image-creator-env/bin/activate
122
123 You may later deactivate it using:
124
125 .. code-block:: console
126
127    $ deactivate
128
129 kamaki Installation
130 -------------------
131
132 Refer to `./kamaki documentation <http://docs.dev.grnet.gr/kamaki/latest/installation.html>`_
133 for instructions. You may install kamaki from source inside the virtualenv or
134 use binary packages if they are available for your distribution.
135
136 snf-image-creator Installation
137 ------------------------------
138
139 Download the latest snf-image-creator source package from
140 `here <https://code.grnet.gr/projects/snf-image-creator/files>`_ and install it
141 inside the virtualenv using the following commands:
142
143 .. code-block:: console
144
145    $ tar -xf snf_image_creator-<VERSION>.tar.gz
146    $ cd snf_image_creator-<VERSION>
147    $ python ./setup install
148
149 Alternatively, you can install the bleeding edge version of the software by
150 cloning its git repository:
151
152 .. code-block:: console
153
154    $ git clone https://code.grnet.gr/git/snf-image-creator
155    $ cd snf-image-creator
156    $ python ./setup.py install
157
158 To do the latter, you'll need to have git (http://git-scm.com/) installed.
159 For ubuntu this can be done using:
160
161 .. code-block:: console
162
163    $ apt-get install git
164
165 .. warning::
166    Keep in mind that the bleeding edge version may be unstable or even
167    unusable.
168