X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/5c801047994d7357278355d67821f55aedbfcb1a..abfaa6d925335d9599518a4da2c5d26f74f02185:/docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst index cb5451b..4c6f5e9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,90 +1,132 @@ 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 `_ -* Synnefo Linux packages: `http://apt.dev.grnet.gr `_, `http://apt2.dev.grnet.gr `_ +* Kamaki at pypi: `http://pypi.python.org/pypi/kamaki `_ -Linux and Unix-like enviroments -------------------------------- +* Synnefo Linux packages: `http://apt.dev.grnet.gr `_ -Ubuntu and Debian packages -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Linux and Unix-like environments +-------------------------------- + +Debian: +^^^^^^^ The following steps describe a command-line approach, but any graphic package manager can be used instead. -Add the following to apt sources list -""""""""""""""""""""""""""""""""""""" +* As root, append the following to */etc/apt/sources.list* :: -As root, append one of the following to */etc/apt/sources.list*: + deb http://apt.dev.grnet.gr wheezy/ -* Debian Sid (kamaki 0.6.2):: +.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze" - deb http://apt.dev.grnet.gr/ sid main +* Make sure the GPG public key for the Synnefo development team is added: -* Debian Stable (kamaki 0.6.1):: + .. code-block:: console - deb http://apt.dev.grnet.gr/ squeeze main - deb http://apt2.dev.grnet.gr stable/ + $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add - -* Ubuntu (kamaki 0.6.1):: + otherwise *apt-get update* will produce GPG warnings. - deb http://apt.dev.grnet.gr/ precise main +* Update the Debian sources: + .. code-block:: console -Update -"""""" + $ sudo apt-get update -.. note:: make sure the GPG public key for the GRNET dev team is added: +* Install kamaki: .. code-block:: console - $ curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add - + $ sudo apt-get install kamaki - otherwise *apt-get update* will produce GPG warnings. +Ubuntu +^^^^^^ -.. code-block:: console +The following steps describe a command-line approach, but any graphic package +manager can be used instead. - $ sudo apt-get update +* Let ppa take care of the repository configuration: + .. code-block:: console -Install kamaki -"""""""""""""" + $ sudo apt-get install python-software-properties + $ sudo add-apt-repository ppa:grnet/synnefo -.. note:: **versions 0.6.0 - 0.6.1:** +* Update the Debian sources: - The *snf-common* package (available at synnefo apt repository) will be automatically installed as a dependency. + .. code-block:: console -.. note:: **versions 0.6.2 and on:** + $ sudo apt-get update - 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. +* Install kamaki: -.. code-block:: console + .. code-block:: console - $ sudo apt-get install kamaki + $ sudo apt-get install kamaki -Install ansicolors and/or progress (Optional) +Install ansicolors (optional but recommended) """"""""""""""""""""""""""""""""""""""""""""" .. code-block:: console $ sudo apt-get install python-ansicolors - $ sudo apt-get install python-progress -.. _installing-from-source-ref: +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 -Installing from source (git repos.) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. 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 better [http://www.python.org] + * Python 2.6 or 2.7 [http://www.python.org] * Python setuptools [http://pypi.python.org/pypi/setuptools] Optional: @@ -94,157 +136,151 @@ 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 `_ + +Install kamaki +"""""""""""""" + +.. code-block:: console -Install objpool (was: snf-common) -""""""""""""""""""""""""""""""""" + $ pip install kamaki -.. note:: **versions 0.6.0 - 0.6.1** +Install ansicolors +"""""""""""""""""" - 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: +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 +.. code-block:: console - $ git clone http://code.grnet.gr/git/synnefo - $ cd synnefo/snf-common - $ ./setup build install - $ cd - + $ pip install ansicolors -**Version 0.6.2 and on:** +Install mock (developers only) +"""""""""""""""""""""""""""""" -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: +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/objpool - $ cd objpool - $ ./setup build install - $ cd - + $ pip install mock -Install kamaki -"""""""""""""" +.. warning:: mock version >= 1.X -.. code-block:: console +.. hint:: To activate functional tests in kamaki. enable the preconfigured + *livetest* command group: - $ git clone http://code.grnet.gr/git/kamaki - $ cd kamaki - $ ./setup build install + .. code-block:: console -Install progress and/or ansicolors (optional) -""""""""""""""""""""""""""""""""""""""""""""" + $ kamaki config set livetest_cli livetest -progress: command-line progress bars (in some commands) +Install astakosclient +""""""""""""""""""""" -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 + $ 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 ------- -Since version 0.6.2 kamaki can run on Windows, either on standard Windows console, or inside an improved command line shell. The present guide presents a tested method for using kamaki in windows +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 `here `_) +* Python 2.7 or better (`Official versions `_) -* Git (download `windows version `_) +* Setuptools (`Official versions and workarounds `_) -* Setuptools (Official versions and workarrounds `here `_) +Users who have already set up and wokring python and setuptools (e.g., for +another project) may skip Python and / or setuptools installation. -Installation from source -^^^^^^^^^^^^^^^^^^^^^^^^ - -Install python -"""""""""""""" +Install Python +^^^^^^^^^^^^^^ -Download and run the Windows installer from `here `_ +Download and run the Windows installer from +`here `_ -Users should pick the installer that fits their windows version and architecture. +Users should pick the installer that fits their windows version and machine +architecture. -Add python to windows path -"""""""""""""""""""""""""" +Add Python to windows path +^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following will allow users to run python and python scripts from command line. +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** +* 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: +* Without removing existing values, append the following to PATH:: - C:\Python;C:\Python\Scripts + ;C:\Python27;C:\Python27\Scripts - .. note:: Path values are separated by a semicolons +.. note:: Path values are separated by semicolons - .. warning:: C:\Python should be replaced with the actual python path in the system, e.g. C:\Python27 +.. 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, the script is downloaded at C:\Downloads:: +^^^^^^^^^^^^^^^^^^ - C:\> cd Downloads - C:\Downloads\> python ez_setup.py - ... - Installation finished - C:\Downloads\> +According to the corresponding +`python org page `_, the setuptools +installer doesn't currently work on 64bit machines. -Install GIT -""""""""""" +* Users with 32-bit operating systems should download and run the graphic + installer -Download GIT from `here `_ and run the graphic installer. During the installation, users will be able to modify some installation options. The present guide is tested with the default selections. +* 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:: -After the installation is completed, a GIT standalone shell will be installed (a desktop shortcut is created, by default). Users are advised to run kamaki through this shell. + C:\> cd Downloads + C:\Downloads\> python ez_setup.py + ... + Installation finished + C:\Downloads\> Install kamaki -"""""""""""""" - -* Run the GIT standalone shell - -* Enter the location where kamaki will be installed, e.g. *C\:* - -.. code-block:: console - - $ cd /c/ - -* Download source from GRNET repository +^^^^^^^^^^^^^^ .. code-block:: console - $ git clone http://code.grnet.gr/git/kamaki - Cloning into 'kamaki'... - Receiving objects: ... - Resolving Deltas: ... - -* Enter source and install kamaki - -.. code-block:: console - - $ cd kamaki - $ python setup.py install - running install - ... - Finished processing dependencies for kamaki==0.6.2 - -.. warning:: kamaki version should be 0.6.2 or better, otherwise it will not function. Users can test that by running:: - - $ kamaki --version + $ easy_install kamaki