Bump version to 0.2.7

[snf-image-creator] / docs / install.rst

diff --git a/docs/install.rst b/docs/install.rst
index 6f2880d..dfd0dd4 100644 (file)
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -1,10 +1,9 @@
 Installation
 ^^^^^^^^^^^^
 
 Installation
 ^^^^^^^^^^^^
 

-This guide describes how to install snf-image-creator on an Ubuntu 12.04 LTS
-system. It is highly recommended to have virtualization capable hardware.
-snf-image-creator will work on processors that do not support virtualization
-but it will be extremely slow.
+This guide describes how to install snf-image-creator on a Linux system. It is
+highly recommended to have virtualization capable hardware. snf-image-creator
+will work on processors that do not support virtualization but it will be slow.

 
 Dependencies
 ============
 
 Dependencies
 ============

@@ -15,187 +14,254 @@ snf-image-creator depends on the following programs:
  * Python setuptools [http://pypi.python.org/pypi/setuptools]
  * Python Dialog [http://pythondialog.sourceforge.net/]
  * Python bindings for libguestfs [http://libguestfs.org/]
  * Python setuptools [http://pypi.python.org/pypi/setuptools]
  * Python Dialog [http://pythondialog.sourceforge.net/]
  * Python bindings for libguestfs [http://libguestfs.org/]

- * Kamaki [https://code.grnet.gr/projects/kamaki]
+ * Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]
+ * pyparted [https://fedorahosted.org/pyparted/]
+ * rsync [http://rsync.samba.org/]
+ * ./kamaki [https://code.grnet.gr/projects/kamaki]

  * Python sh (previously pbs) [https://github.com/amoffat/sh]
  * ANSI colors for Python [http://pypi.python.org/pypi/ansicolors]
  * progress [http://pypi.python.org/pypi/progress]
  * Python sh (previously pbs) [https://github.com/amoffat/sh]
  * ANSI colors for Python [http://pypi.python.org/pypi/ansicolors]
  * progress [http://pypi.python.org/pypi/progress]

- * Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]

 
 The above dependencies are resolved differently, depending on the installation
 
 The above dependencies are resolved differently, depending on the installation

-method you choose.
+method you choose. There are two installation methods available:

 
 

-There are two installation methods. The first uses official packages whereas
-the second installs snf-image-creator and its dependencies from source. Both
-methods are presented below.
+#. `Installation using packages <#install-snf-image-creator-using-packages>`_

 
 

-Install snf-image-creator using official packages
-=================================================
+#. `Installation from source <#install-snf-image-creator-from-source>`_

 
 

-This method of installing snf-image-creator has all the advantages of Ubuntu's
-APT installation:
+Install snf-image-creator using packages
+========================================

 
 

-* Automatic resolution of dependencies
-* Simple installation of consequent updates
+Ubuntu
+------

 
 

-In order to proceed with the installation, you must first add GRNET's dev repo
-to your sources. You can use the following commands:
+For *Ubuntu 12.04 LTS* and *12.10* systems, you can use our official packages
+found in *grnet/synnefo* Lauchpad PPA.
+
+Add the synnefo PPA in your system:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   cd /etc/apt/sources.list.d
-   echo "deb http://apt.dev.grnet.gr precise main" | \
-   sudo tee -a  apt.dev.grnet.gr.list
-   echo "deb-src http://apt.dev.grnet.gr precise main" | \
-   sudo tee -a apt.dev.grnet.gr.list
+   $ sudo apt-add-repository ppa:grnet/synnefo
+   $ sudo apt-get update
+
+If *apt-add-repository* is missing, first install:

 
 

-You will also need to import the repo's GPG key. You can use the ``curl`` tool
-for this.
+*software-properties-common* (Ubuntu 12.10):

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ sudo apt-get install curl
+   $ sudo apt-get install software-properties-common

 
 

-Use the following command to import the GPG key:
+Or *python-software-properties* (Ubuntu 12.04):

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub | sudo apt-key add -
+   $ sudo apt-get install python-software-properties

 
 

-You can verify that the repo has been added successfully if snf-image-creator
-exists as a package. First do an update of your sources:
+After the synnefo repository is set up, you should be able to list
+snf-image-creator by calling:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ sudo apt-get update
+   $ apt-cache showpkg snf-image-creator

 
 

-then check if snf-image-creator exists with the following command:
+Install the package by issuing:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ apt-cache showpkg snf-image-creator
+   $ sudo apt-get install snf-image-creator
+
+.. note::
+   If you are asked during the installation to create/update a
+   "supermin appliance", choose "Yes".
+
+.. warning::
+   In *Ubuntu 12.10* the current package of libguestfs (1.18-2) is broken. Take
+   a look at the open `bug report <https://bugs.launchpad.net/ubuntu/quantal/+source/libguestfs/+bug/1086974>`_.
+   Until version 1.18-2ubunut1 is out, you may workaround this problem by
+   creating a symlink like this:
+
+   *sudo ln -s /usr/lib/guestfs /usr/lib/x86_64-linux-gnu/guestfs*

 
 

-If GRNET's dev repo has been added successfully, you can install
-snf-image-creator, along with its dependencies, with the following command:
+Fedora
+------
+
+For *Fedora 17* you can use our official packages hosted at the *synnefo*
+repository of the openSUSE Build Service.
+
+Add the *synnefo* repository for *Fedora 17* to *yum*:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ sudo apt-get install snf-image-creator
+   $ cd /etc/yum.repos.d
+   $ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/Fedora_17/home:GRNET:synnefo.repo

 
 

-The installation might take a while. Please note that at some point during the
-installation you will be prompted to create/update a "supermin appliance". This
-is a setting regarding libguestfs and you can safely choose "Yes".
+To list the *snf-image-creator* package use the following command:

 
 

-Install snf-image-creator from source
-=====================================
+.. code-block:: console

 
 

-This method provides you with the cutting edge of snf-image-creator, which
-gives you access to all the latest features. Keep in mind, however,
-that you may experience instability issues.
+   $ yum info snf-image-creator

 
 

-The first four dependencies (python2, setuptools, Python-Dialog, and
-libguestfs) need to be installed manually by the user. In an Ubuntu 12.04 LTS
-system this can be achieved by installing packages provided by the
-distribution, using the following command:
+Install the package by issuing:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ apt-get install python-setuptools python-guestfs python-dialog
+   $ yum install snf-image-creator

 
 

-The rest of the dependencies will be automatically resolved by setuptools.
-Note that at some point during the installation, you will be prompted to
-create/update a "supermin appliance". This is a setting regarding libguestfs
-and you can safely choose "Yes".
+CentOS
+------

 
 

-In order to download the source files, git needs to be installed. You can do
-so with the following command:
+For *CentOS 6* you can use our official packages hosted at the *synnefo*
+repository of the openSUSE Build Service.
+
+Add the *synnefo* repository for *CentOS 6* to the yum repositories list:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ apt-get install git
+   $ cd /etc/yum.repos.d
+   $ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/CentOS_CentOS-6/home:GRNET:synnefo.repo

 
 

-Python Virtual Environment
---------------------------
+Check the `Fedora <#fedora>`_ instructions on how to install the software.

 
 

-Since snf-image-creator and the rest of its dependencies won't be installed
-using packages, it's better to work in an isolated python virtual environment
-(virtualenv). Installing the Virtual Python Environment builder in Ubuntu can
-be accomplished using the following command:
+Arch Linux
+----------
+
+For *Arch Linux* there are **unofficial** packages in AUR:
+https://aur.archlinux.org/packages/snf-image-creator/ kindly provided by
+Axilleas Pipinellis <axilleas@archlinux.info>.
+
+.. note::
+    Those packages are not maintained by the Synnefo development team.
+
+    Please direct package-specific questions to Axilleas Pipinellis <axilleas@archlinux.info>,
+    Cc: the Synnefo development team <synnefo-devel@googlegroups.com>
+
+To install the package you may use *yaourt*. Create and install
+the *yaourt* package:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ apt-get install python-virtualenv
+   $ wget https://aur.archlinux.org/packages/pa/package-query/package-query.tar.gz
+   $ tar -xvf package-query.tar.gz
+   $ cd package-query
+   $ makepkg -s
+   $ pacman -U package-query-<VERSION>-<ARCH>.pkg.tar.xz
+   $ cd ..
+   $ wget https://aur.archlinux.org/packages/ya/yaourt/yaourt.tar.gz
+   $ tar -xvf yaourt.tar.gz
+   $ cd yaourt
+   $ makepkg -s
+   $ pacman -U yaourt-<VERSION>-<ARCH>.pkg.tar.xz

 
 

-Now, create a new python virtual environment like this:
+Install *snf-image-creator* using yaourt:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ virtualenv --system-site-packages ~/image-creator-env
+   $ yaourt -Sa snf-image-creator

 
 

-and activate it by executing:
+Install snf-image-creator from source
+=====================================
+
+Manually install the following dependencies:

 
 

+ * Python 2 [http://www.python.org/]
+ * Python setuptools [http://pypi.python.org/pypi/setuptools]
+ * Python Dialog [http://pythondialog.sourceforge.net/]
+ * Python bindings for libguestfs [http://libguestfs.org/]
+ * Python interface to sendfile [http://pypi.python.org/pypi/pysendfile]
+ * pyparted [https://fedorahosted.org/pyparted/]
+ * rsync [http://rsync.samba.org/]
+
+In Ubuntu you can do this using:
+ 

 .. code-block:: console
 
 .. code-block:: console
 

-   $ source ~/image-creator-env/bin/activate
+   $ sudo apt-get install python-setuptools python-guestfs python-dialog \
+     python-sendfile python-parted rsync

 
 

-You can later deactivate it using the following command:
+If you are using Ubuntu 12.10 you also need to install libguestfs-tools:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ deactivate
+   $ sudo apt-get install libguestfs-tools

 
 

-snf-common Installation
------------------------
+.. note::
+   If you are asked during the installation to create/update a
+   "supermin appliance", choose "Yes".

 
 

-Install snf-common from source, by cloning it's repository:
+Python Virtual Environment
+--------------------------

 
 

-.. code-block:: console
+Since snf-image-creator and the rest of its dependencies won't be installed
+using packages, it's better to work in an isolated python virtual environment
+(virtualenv).

 
 

-   $ cd ~
-   $ git clone https://code.grnet.gr/git/synnefo
-   $ cd synnefo/snf-common
-   $ python setup.py build
+Install the Virtual Python Environment builder:
+http://pypi.python.org/pypi/virtualenv.

 
 

-Then, make sure you are within the activated virtual environment before you
-execute:
+For Ubuntu use the following command:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ python setup.py install
+   $ sudo apt-get install python-virtualenv

 
 

-kamaki Installation
--------------------
+Then create a new python virtual environment:
+
+.. code-block:: console
+
+   $ virtualenv --system-site-packages ~/image-creator-env

 
 

-Install kamaki from source, by cloning it's repository:
+and activate it by executing:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ cd ~
-   $ git clone https://code.grnet.gr/git/kamaki
-   $ cd kamaki
-   $ ./setup.py build
+   $ source ~/image-creator-env/bin/activate

 
 

-As above, make sure you are within the activated virtual environment before you
-execute:
+You may later deactivate it using:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ ./setup.py install
+   $ deactivate
+
+kamaki Installation
+-------------------
+
+Refer to `./kamaki documentation <http://docs.dev.grnet.gr/kamaki/latest/installation.html>`_
+for instructions. You may install kamaki from source inside the virtualenv
+you've created above or by using binary packages if they are available for your
+distribution.

 
 snf-image-creator Installation
 ------------------------------
 
 
 snf-image-creator Installation
 ------------------------------
 

-Install snf-image-creator the same way:
+Download the latest snf-image-creator source package from
+`here <https://code.grnet.gr/projects/snf-image-creator/files>`_ and install it
+inside the virtualenv using the following commands:
+
+.. code-block:: console
+
+   $ tar -xf snf_image_creator-<VERSION>.tar.gz
+   $ cd snf_image_creator-<VERSION>
+   $ python ./setup.py install
+
+Alternatively, you can install the bleeding edge version of the software by
+cloning its git repository:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ cd ~

    $ git clone https://code.grnet.gr/git/snf-image-creator
    $ git clone https://code.grnet.gr/git/snf-image-creator

-   $ git checkout stable-0.1

    $ cd snf-image-creator
    $ cd snf-image-creator

-   $ ./setup.py build
+   $ python ./setup.py install

 
 

-And from within the virtual environment execute:
+To do the latter, you'll need to have git (http://git-scm.com/) installed.
+For ubuntu this can be done using:

 
 .. code-block:: console
 
 
 .. code-block:: console
 

-   $ ./setup.py install
+   $ sudo apt-get install git
+
+.. warning::
+   Keep in mind that the bleeding edge version may be unstable or even
+   unusable.
+