X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/961e60407e66be1e9db8df1fb36509268bcff888..abfaa6d925335d9599518a4da2c5d26f74f02185:/docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst index 09cb261..4c6f5e9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,136 +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 +-------------------------------- + +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 -.. _installing-from-source-ref: -Installing from source (git repos.) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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 better [http://www.python.org] + * 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] -1. Setup a virtual enviroment (optional) -"""""""""""""""""""""""""""""""""""""""" +Setup a virtual enviroment (optional) +""""""""""""""""""""""""""""""""""""" -With virtualenv users can setup kamaki and synnefo services in a sandbox environment. +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 `_ +A more detailed example of using virtual env can be found at the +`snf-image-creator setup guide `_ -2. Install snf-common -""""""""""""""""""""" - -Package snf-common is part of the synnefo project and is a kamaki dependency since version 0.6.0. +Install kamaki +"""""""""""""" .. code-block:: console - $ git clone http://code.grnet.gr/git/synnefo + $ pip install kamaki + +Install ansicolors +"""""""""""""""""" - $ cd synnefo/snf-common +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. - $ ./setup build install +.. code-block:: console + + $ pip install ansicolors - $ cd - +Install mock (developers only) +"""""""""""""""""""""""""""""" -3. Install kamaki -""""""""""""""""" +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 - $ git clone http://code.grnet.gr/git/kamaki + $ pip install mock - $ cd kamaki +.. warning:: mock version >= 1.X - $ ./setup build install +.. hint:: To activate functional tests in kamaki. enable the preconfigured + *livetest* command group: -4. Install progress and/or ansicolors (optional) -"""""""""""""""""""""""""""""""""""""""""""""""" + .. code-block:: console -progress: command-line progress bars (in some commands) + $ kamaki config set livetest_cli livetest -ansicolors: color kamaki output (can switched on and off in `setup `_) +Install astakosclient +""""""""""""""""""""" + +A seperate project called +`astakosclient `_ can be used for +advanced user and service management. .. code-block:: console - $ pip install progress + $ pip install astakosclient - $ pip install ansicolors +.. hint:: To activate astakosclient commands in kamaki, enable the + preconfigured *astakos* command group: -Ubuntu and Debian packages -^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. code-block:: console -The following steps describe a command-line approach, but any graphic package manager can be used instead. + $ kamaki config set astakos_cli astakos -1. Add the following to apt sources list -"""""""""""""""""""""""""""""""""""""""" +Mac OS X +-------- -* Debian:: +Kamaki can be installed on Mac OS X systems from source, by following the steps +at :ref:`installing-from-pypi-ref`. - deb http://apt.dev.grnet.gr/ sid main +Windows +------- -* Ubuntu:: +Kamaki can be installed on Windows by following the pypi method. Installing the +requirements is a bit different than in other systems. - deb http://apt.dev.grnet.gr/ precise main +The full process is detailed in the following: -2. Update -""""""""" +Requirements +^^^^^^^^^^^^ -.. code-block:: console +* Python 2.7 or better (`Official versions `_) - $ sudo apt-get update +* Setuptools (`Official versions and workarounds `_) -.. note:: Safely ignore a signature verification error like the following, if it emerges: +Users who have already set up and wokring python and setuptools (e.g., for +another project) may skip Python and / or setuptools installation. - .. warning:: GPG error: http://apt.dev.grnet.gr precise/sid InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY XXXXXXXX +Install Python +^^^^^^^^^^^^^^ -3. Install kamaki -""""""""""""""""" +Download and run the Windows installer from +`here `_ -Since version 0.6.0, the package snf-common (available at synnefo apt repository) will be automatically installed as a dependency. +Users should pick the installer that fits their windows version and machine +architecture. -.. code-block:: console +Add Python to windows path +^^^^^^^^^^^^^^^^^^^^^^^^^^ - $ sudo apt-get install kamaki +The following will allow users to run Python and Python scripts from command +line. -4. Install ansicolors and/or progress (Optional) -"""""""""""""""""""""""""""""""""""""""""""""""" +* Select **System** from the Control Panel, select the **Advanced** tab, the + **Environment Variables** button and then find the **PATH** (user or + system) and **edit** -.. code-block:: console +* Without removing existing values, append the following to PATH:: - $ sudo apt-get install python-ansicolors + ;C:\Python27;C:\Python27\Scripts - $ sudo apt-get install python-progress +.. note:: Path values are separated by semicolons -Mac OS X --------- +.. warning:: In case of a different version, C:\\Python27 should be replaced + with the actual python path in the system -Kamaki can be installed on Mac OS X systems from source, by following the steps at :ref:`installing-from-source-ref`. +Install setuptools +^^^^^^^^^^^^^^^^^^ -Windows -------- +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 -It has proven possible (and not too tricky) to install kamaki on Windows console using some auxiliary applications, but Windows users are not the target audience for the time being. + $ easy_install kamaki