X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/f5f2dc533598070b760bd9c4045ec5a29d8d14e3..abfaa6d925335d9599518a4da2c5d26f74f02185:/docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst index 81fb712..4c6f5e9 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,15 +1,20 @@ 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 `_ + +Linux and Unix-like environments +-------------------------------- Debian: ^^^^^^^ @@ -18,10 +23,11 @@ The following steps describe a command-line approach, but any graphic package ma * As root, append the following to */etc/apt/sources.list* :: - deb http://apt.dev.grnet.gr/ squeeze main - deb http://apt2.dev.grnet.gr stable/ + deb http://apt.dev.grnet.gr wheezy/ + +.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze" -* Make sure the GPG public key for the GRNET dev team is added: +* Make sure the GPG public key for the Synnefo development team is added: .. code-block:: console @@ -44,7 +50,8 @@ The following steps describe a command-line approach, but any graphic package ma Ubuntu ^^^^^^ -The following steps describe a command-line approach, but any graphic package manager can be used instead. +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: @@ -65,25 +72,61 @@ The following steps describe a command-line approach, but any graphic package ma $ sudo apt-get install kamaki -Install ansicolors and/or progress (Optional but recommended) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +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 + +.. 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. -Installing from source (git repos.) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. 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: @@ -93,155 +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 objpool (was: snf-common) -""""""""""""""""""""""""""""""""" - -Kamaki is based on python-objpool. The objpool package is easy to install from source, even on windows platforms: +Install kamaki +"""""""""""""" .. code-block:: console - $ git clone http://code.grnet.gr/git/objpool - $ cd objpool - $ ./setup build install - $ cd - + $ pip install kamaki -Install kamaki -"""""""""""""" +Install ansicolors +"""""""""""""""""" -Kamaki can be downloaded from `this location `_, where users can pick the version they prefer and unzip it locally: +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 - $ tar xvfz kamaki-0.7.tar.gz + $ pip install ansicolors + +Install mock (developers only) +"""""""""""""""""""""""""""""" -or it can be downloaded directly from the git repository: +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 -and then installed by the setup script: +.. warning:: mock version >= 1.X -.. code-block:: console +.. hint:: To activate functional tests in kamaki. enable the preconfigured + *livetest* command group: - $ 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 ------- -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 setting up 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 `_) -* Git (download `windows version `_) - * Setuptools (`Official versions and workarounds `_) -Installation from source -^^^^^^^^^^^^^^^^^^^^^^^^ +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 -"""""""""""""" +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:: - C:\Python;C:\Python\Scripts + ;C:\Python27;C:\Python27\Scripts .. 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. +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 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:: +* 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 GIT -""""""""""" - -`Download GIT `_ 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. - -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.7 +.. code-block:: console - $ kamaki --version + $ easy_install kamaki