X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/010e8c7c9b1d42dafdf6124e791299ac1eca7bf2..abfaa6d925335d9599518a4da2c5d26f74f02185:/docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst index dc4f03f..4c6f5e9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,151 +1,286 @@ Installation ============ -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 advanced Linux/Unix-like users, it should be quite straightforward 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. * Kamaki repository: `http://code.grnet.gr/git/kamaki `_ +* Kamaki at pypi: `http://pypi.python.org/pypi/kamaki `_ + * Synnefo Linux packages: `http://apt.dev.grnet.gr `_ -Linux and Unix-like enviroments -------------------------------- +Linux and Unix-like environments +-------------------------------- -.. _installing-from-source-ref: +Debian: +^^^^^^^ -Installing from source (git repos.) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following steps describe a command-line approach, but any graphic package manager can be used instead. -Requirements -"""""""""""" +* As root, append the following to */etc/apt/sources.list* :: -Essential: + deb http://apt.dev.grnet.gr wheezy/ - * Python 2.6 or better [http://www.python.org] - * Python setuptools [http://pypi.python.org/pypi/setuptools] +.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze" -Optional: +* Make sure the GPG public key for the Synnefo development team is added: - * VirtualEnv (python-virtualenv) [http://www.virtualenv.org] + .. code-block:: console -1. Setup a virtual enviroment (optional) -"""""""""""""""""""""""""""""""""""""""" + $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add - -With virtualenv users can setup kamaki and synnefo services in a sandbox environment. + otherwise *apt-get update* will produce GPG warnings. -.. code-block:: console +* Update the Debian sources: - $ virtualenv kamaki-env - $ source kamaki-env/bin/activate + .. code-block:: console + + $ sudo apt-get update + +* Install kamaki: + + .. code-block:: console -A more detailed example of using virtual env can be found at the `snf-image-creator setup guide `_ + $ sudo apt-get install kamaki -2. Install objpool (was: snf-common) -"""""""""""""""""""""""""""""""""""""""""" +Ubuntu +^^^^^^ -.. note:: **versions 0.6.0 - 0.6.1** +The following steps describe a command-line approach, but any graphic package +manager can be used instead. - Package snf-common is part of the synnefo project and used to be a kamaki dependency in versions from 0.6.0 to 0.6.1 to provide a connection pooling mechanism. Users who still run 0.6.0 or 0.6.1 may need to manually install the snf-common package: +* Let ppa take care of the repository configuration: .. code-block:: console - $ git clone http://code.grnet.gr/git/synnefo - $ cd synnefo/snf-common - $ ./setup build install - $ cd - + $ 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: -**Version 0.6.2 and on:** + .. code-block:: console + + $ sudo apt-get install kamaki -Since 0.6.2, kamaki is based on objpool (hence the snf-common dependency is now obsolete). The objpool package is easy to install from source, even on windows platforms: +Install ansicolors (optional but recommended) +""""""""""""""""""""""""""""""""""""""""""""" .. code-block:: console - $ git clone http://code.grnet.gr/git/objpool - $ cd objpool - $ ./setup build install - $ cd - + $ sudo apt-get install python-ansicolors -3. Install kamaki -""""""""""""""""" +Install mock (for developers only) +"""""""""""""""""""""""""""""""""" .. code-block:: console - $ git clone http://code.grnet.gr/git/kamaki - $ cd kamaki - $ ./setup build install + $ 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 -4. Install progress and/or ansicolors (optional) -"""""""""""""""""""""""""""""""""""""""""""""""" -progress: command-line progress bars (in some commands) +Install astakosclient (optional) +"""""""""""""""""""""""""""""""" -ansicolors: color kamaki output (can switched on and off in `setup `_) +A seperate project called +`astakosclient `_ can be used for +advanced user and service management. .. code-block:: console - $ pip install progress - $ pip install ansicolors + $ apt-get install python-astakosclient -Ubuntu and Debian packages -^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. hint:: To activate astakosclient commands in kamaki, enable the + preconfigured *astakos* command group: -The following steps describe a command-line approach, but any graphic package manager can be used instead. + .. code-block:: console + + $ kamaki config set astakos_cli astakos + +.. _installing-from-pypi-ref: -1. Add the following to apt sources list -"""""""""""""""""""""""""""""""""""""""" +Installing from pypi +^^^^^^^^^^^^^^^^^^^^ -* Debian:: +Requirements +"""""""""""" - deb http://apt.dev.grnet.gr/ sid main +Essential: -* Ubuntu:: + * Python 2.6 or 2.7 [http://www.python.org] + * Python setuptools [http://pypi.python.org/pypi/setuptools] + +Optional: + + * VirtualEnv (python-virtualenv) [http://www.virtualenv.org] - deb http://apt.dev.grnet.gr/ precise main +Setup a virtual enviroment (optional) +""""""""""""""""""""""""""""""""""""" -2. Update -""""""""" +With virtualenv users can setup kamaki and Synnefo services in a sandbox +environment. .. code-block:: console - $ sudo apt-get update + $ virtualenv kamaki-env + $ source kamaki-env/bin/activate -.. note:: Don't forget to get the GPG public key for the GRNET dev team: +A more detailed example of using virtual env can be found at the +`snf-image-creator setup guide `_ - .. code-block:: console +Install kamaki +"""""""""""""" - $ curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add - +.. code-block:: console - otherwise *apt-get update* will produce GPG warnings. + $ pip install kamaki + +Install ansicolors +"""""""""""""""""" -3. Install kamaki -""""""""""""""""" +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. -.. note:: **versions 0.6.0 - 0.6.1:** +.. code-block:: console - The *snf-common* package (available at synnefo apt repository) will be automatically installed as a dependency. + $ pip install ansicolors -.. note:: **versions 0.6.2 and on:** +Install mock (developers only) +"""""""""""""""""""""""""""""" - Since version 0.6.2, *objpool* replaces *snf-common*. The objpool package is also available at synnefo repository and is automatically installed as a dependency. The *snf-common* dependency is removed. +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 - $ sudo apt-get install kamaki + $ pip install mock + +.. warning:: mock version >= 1.X + +.. hint:: To activate functional tests in kamaki. enable the preconfigured + *livetest* command group: + + .. code-block:: console -4. Install ansicolors and/or progress (Optional) -"""""""""""""""""""""""""""""""""""""""""""""""" + $ 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 - $ sudo apt-get install python-ansicolors - $ sudo apt-get install python-progress + $ 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-source-ref`. +Kamaki can be installed on Mac OS X systems from source, by following the steps +at :ref:`installing-from-pypi-ref`. Windows ------- -Although it is proven not too tricky to install kamaki on Windows console using `git for windows `_, Windows environments are not supported at the time being. +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