X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/4067cdaf1e3e61752ac41e6a8910a901ef5e8400..abfaa6d925335d9599518a4da2c5d26f74f02185:/docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst index cd5bac1..4c6f5e9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,22 +1,286 @@ Installation ============ -This guide describes the standard installation proccess for kamaki, with the aspiration of covering as much cases as possible. Although kamaki was initially targeted to advanced Linux/Unix-like users, it should be quite straigh forward to install and have it up and running in most popular platforms. +This guide describes the standard installation process for kamaki, with the +aspiration of covering as much cases as possible. Although kamaki was initially +targeted to Linux/Unix-like users, it is quite straightforward to install and +have it up and running in all platforms running Python 2.6 or 2.7. -Linux and Unix-like enviroments -------------------------------- -Installing from source (git repos.) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* Kamaki repository: `http://code.grnet.gr/git/kamaki `_ -Ubuntu and Debian packages -^^^^^^^^^^^^^^^^^^^^^^^^^^ +* Kamaki at pypi: `http://pypi.python.org/pypi/kamaki `_ + +* Synnefo Linux packages: `http://apt.dev.grnet.gr `_ + +Linux and Unix-like environments +-------------------------------- + +Debian: +^^^^^^^ + +The following steps describe a command-line approach, but any graphic package manager can be used instead. + +* As root, append the following to */etc/apt/sources.list* :: + + deb http://apt.dev.grnet.gr wheezy/ + +.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze" + +* Make sure the GPG public key for the Synnefo development team is added: + + .. code-block:: console + + $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add - + + otherwise *apt-get update* will produce GPG warnings. + +* Update the Debian sources: + + .. code-block:: console + + $ sudo apt-get update + +* Install kamaki: + + .. code-block:: console + + $ sudo apt-get install kamaki + +Ubuntu +^^^^^^ + +The following steps describe a command-line approach, but any graphic package +manager can be used instead. + +* Let ppa take care of the repository configuration: + + .. code-block:: console + + $ sudo apt-get install python-software-properties + $ sudo add-apt-repository ppa:grnet/synnefo + +* Update the Debian sources: + + .. code-block:: console + + $ sudo apt-get update + +* Install kamaki: + + .. code-block:: console + + $ sudo apt-get install kamaki + +Install ansicolors (optional but recommended) +""""""""""""""""""""""""""""""""""""""""""""" + +.. code-block:: console + + $ sudo apt-get install python-ansicolors + +Install mock (for developers only) +"""""""""""""""""""""""""""""""""" + +.. code-block:: console + + $ sudo apt-get install python-mock + +.. warning:: kamaki.clients unit-tests need python-mock 1.X or better. e.g.:: + + $ sudo apt-get install python-mock=1.0.1 + +.. hint:: To activate functional tests in kamaki. enable the preconfigured + *livetest* command group: + + .. code-block:: console + + $ kamaki config set livetest_cli livetest + + +Install astakosclient (optional) +"""""""""""""""""""""""""""""""" + +A seperate project called +`astakosclient `_ can be used for +advanced user and service management. + +.. code-block:: console + + $ apt-get install python-astakosclient + +.. hint:: To activate astakosclient commands in kamaki, enable the + preconfigured *astakos* command group: + + .. code-block:: console + + $ kamaki config set astakos_cli astakos + +.. _installing-from-pypi-ref: + +Installing from pypi +^^^^^^^^^^^^^^^^^^^^ + +Requirements +"""""""""""" + +Essential: + + * Python 2.6 or 2.7 [http://www.python.org] + * Python setuptools [http://pypi.python.org/pypi/setuptools] + +Optional: -Mac OS ------- + * VirtualEnv (python-virtualenv) [http://www.virtualenv.org] + +Setup a virtual enviroment (optional) +""""""""""""""""""""""""""""""""""""" + +With virtualenv users can setup kamaki and Synnefo services in a sandbox +environment. + +.. code-block:: console + + $ virtualenv kamaki-env + $ source kamaki-env/bin/activate + +A more detailed example of using virtual env can be found at the +`snf-image-creator setup guide `_ + +Install kamaki +"""""""""""""" + +.. code-block:: console + + $ pip install kamaki + +Install ansicolors +"""""""""""""""""" + +The **ansicolors** package is not required for running kamaki, but it is +recommended as a user experience improvement. In specific, ansicolors +adds colors to kamaki responses. + +.. code-block:: console + + $ pip install ansicolors + +Install mock (developers only) +"""""""""""""""""""""""""""""" + +The **mock** package is needed for running the prepared unit-tests in the +kamaki.clients package. This feature is useful when extending / debugging +kamaki functionality and is aimed to kamaki developers and contributors. +Therefore, users can enjoy the full kamaki user experience without installing +mock. + +.. code-block:: console + + $ pip install mock + +.. warning:: mock version >= 1.X + +.. hint:: To activate functional tests in kamaki. enable the preconfigured + *livetest* command group: + + .. code-block:: console + + $ kamaki config set livetest_cli livetest + +Install astakosclient +""""""""""""""""""""" + +A seperate project called +`astakosclient `_ can be used for +advanced user and service management. + +.. code-block:: console + + $ pip install astakosclient + +.. hint:: To activate astakosclient commands in kamaki, enable the + preconfigured *astakos* command group: + + .. code-block:: console + + $ kamaki config set astakos_cli astakos + +Mac OS X +-------- + +Kamaki can be installed on Mac OS X systems from source, by following the steps +at :ref:`installing-from-pypi-ref`. Windows ------- -Installing from source (git repos.) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Kamaki can be installed on Windows by following the pypi method. Installing the +requirements is a bit different than in other systems. + +The full process is detailed in the following: + +Requirements +^^^^^^^^^^^^ + +* Python 2.7 or better (`Official versions `_) + +* Setuptools (`Official versions and workarounds `_) + +Users who have already set up and wokring python and setuptools (e.g., for +another project) may skip Python and / or setuptools installation. + +Install Python +^^^^^^^^^^^^^^ + +Download and run the Windows installer from +`here `_ + +Users should pick the installer that fits their windows version and machine +architecture. + +Add Python to windows path +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following will allow users to run Python and Python scripts from command +line. + +* Select **System** from the Control Panel, select the **Advanced** tab, the + **Environment Variables** button and then find the **PATH** (user or + system) and **edit** + +* Without removing existing values, append the following to PATH:: + + ;C:\Python27;C:\Python27\Scripts + +.. note:: Path values are separated by semicolons + +.. warning:: In case of a different version, C:\\Python27 should be replaced + with the actual python path in the system + +Install setuptools +^^^^^^^^^^^^^^^^^^ + +According to the corresponding +`python org page `_, the setuptools +installer doesn't currently work on 64bit machines. + +* Users with 32-bit operating systems should download and run the graphic + installer + +* Users with 64-bit machines should download the + `ez_setup.py `_ script and + install it from a command shell. In the following example, the script was + downloaded at C:\\Downloads:: + + C:\> cd Downloads + C:\Downloads\> python ez_setup.py + ... + Installation finished + C:\Downloads\> + +Install kamaki +^^^^^^^^^^^^^^ + +.. code-block:: console + + $ easy_install kamaki