X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/010e8c7c9b1d42dafdf6124e791299ac1eca7bf2..ae0c3728b523de860593a587b411aaeaaf80dbce:/docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst index dc4f03f..339971e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,151 +1,285 @@ 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 +^^^^^^ + +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 -.. note:: **versions 0.6.0 - 0.6.1** + $ sudo apt-get install python-software-properties + $ sudo add-apt-repository ppa:grnet/synnefo - 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: +* Update the Debian sources: .. code-block:: console - $ git clone http://code.grnet.gr/git/synnefo - $ cd synnefo/snf-common - $ ./setup build install - $ cd - + $ sudo apt-get update -**Version 0.6.2 and on:** +* 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: + .. code-block:: console + + $ sudo apt-get install kamaki + +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 -4. Install progress and/or ansicolors (optional) -"""""""""""""""""""""""""""""""""""""""""""""""" +.. hint:: To activate functional tests in kamaki. enable the preconfigured + *livetest* command group: + + .. code-block:: console + + $ kamaki config set livetest_cli livetest -progress: command-line progress bars (in some commands) -ansicolors: color kamaki output (can switched on and off in `setup `_) +Install astakosclient (optional) +"""""""""""""""""""""""""""""""" + +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 -1. Add the following to apt sources list -"""""""""""""""""""""""""""""""""""""""" +.. _installing-from-pypi-ref: -* Debian:: +Installing from pypi +^^^^^^^^^^^^^^^^^^^^ + +Requirements +"""""""""""" - deb http://apt.dev.grnet.gr/ sid main +Essential: + + * Python 2.6 or 2.7 [http://www.python.org] + * Python setuptools [http://pypi.python.org/pypi/setuptools] + +Optional: -* Ubuntu:: + * 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 -3. Install kamaki -""""""""""""""""" +Install ansicolors +"""""""""""""""""" -.. note:: **versions 0.6.0 - 0.6.1:** +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. - The *snf-common* package (available at synnefo apt repository) will be automatically installed as a dependency. +.. code-block:: console + + $ 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 -4. Install ansicolors and/or progress (Optional) -"""""""""""""""""""""""""""""""""""""""""""""""" +.. 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 - $ 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 setup tools 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