code.grnet.gr Git - kamaki/blob - docs/installation.rst

   1 Installation
   2 ============
   3
   4 This guide describes the standard installation process for kamaki, with the
   5 aspiration of covering as much cases as possible. Although kamaki was initially
   6 targeted to Linux/Unix-like users, it is quite straightforward to install and
   7 have it up and running in all platforms running Python 2.6 or 2.7.
   8
   9
  10 * Kamaki repository: `http://code.grnet.gr/git/kamaki <http://code.grnet.gr/git/kamaki>`_
  11
  12 * Kamaki at pypi: `http://pypi.python.org/pypi/kamaki <https://pypi.python.org/pypi/kamaki>`_
  13
  14 * Synnefo Linux packages: `http://apt.dev.grnet.gr <http://apt.dev.grnet.gr>`_
  15
  16 Linux and Unix-like environments
  17 --------------------------------
  18
  19 Debian:
  20 ^^^^^^^
  21
  22 The following steps describe a command-line approach, but any graphic package manager can be used instead.
  23
  24 * As root, append the following to */etc/apt/sources.list* ::
  25
  26     deb http://apt.dev.grnet.gr wheezy/
  27
  28 .. warning:: Debian Squeeze users may replace "wheezy" with "squeeze"
  29
  30 * Make sure the GPG public key for the Synnefo development team is added:
  31
  32     .. code-block:: console
  33
  34         $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add -
  35
  36     otherwise *apt-get update* will produce GPG warnings.
  37
  38 * Update the Debian sources:
  39
  40     .. code-block:: console
  41
  42         $ sudo apt-get update
  43
  44 * Install kamaki:
  45
  46     .. code-block:: console
  47
  48         $ sudo apt-get install kamaki
  49
  50 Ubuntu
  51 ^^^^^^
  52
  53 The following steps describe a command-line approach, but any graphic package
  54 manager can be used instead.
  55
  56 * Let ppa take care of the repository configuration:
  57
  58     .. code-block:: console
  59
  60         $ sudo apt-get install python-software-properties
  61         $ sudo add-apt-repository ppa:grnet/synnefo
  62
  63 * Update the Debian sources:
  64
  65     .. code-block:: console
  66
  67         $ sudo apt-get update
  68
  69 * Install kamaki:
  70
  71     .. code-block:: console
  72
  73         $ sudo apt-get install kamaki
  74
  75 Install ansicolors (optional but recommended)
  76 """""""""""""""""""""""""""""""""""""""""""""
  77
  78 .. code-block:: console
  79
  80     $ sudo apt-get install python-ansicolors
  81
  82 Install mock (for developers only)
  83 """"""""""""""""""""""""""""""""""
  84
  85 .. code-block:: console
  86
  87     $ sudo apt-get install python-mock
  88
  89 .. warning:: kamaki.clients unit-tests need python-mock 1.X or better. e.g.::
  90
  91     $ sudo apt-get install python-mock=1.0.1
  92
  93 .. hint:: To activate functional tests in kamaki. enable the preconfigured
  94     *livetest* command group:
  95
  96     .. code-block:: console
  97
  98         $ kamaki config set livetest_cli livetest
  99
 100
 101 Install astakosclient (optional)
 102 """"""""""""""""""""""""""""""""
 103
 104 A seperate project called
 105 `astakosclient <https://pypi.python.org/pypi/astakosclient>`_ can be used for
 106 advanced user and service management.
 107
 108 .. code-block:: console
 109
 110     $ apt-get install python-astakosclient
 111
 112 .. hint:: To activate astakosclient commands in kamaki, enable the
 113     preconfigured *astakos* command group:
 114
 115     .. code-block:: console
 116
 117         $ kamaki config set astakos_cli astakos
 118
 119 .. _installing-from-pypi-ref:
 120
 121 Installing from pypi
 122 ^^^^^^^^^^^^^^^^^^^^
 123
 124 Requirements
 125 """"""""""""
 126
 127 Essential:
 128
 129  * Python 2.6 or 2.7 [http://www.python.org]
 130  * Python setuptools [http://pypi.python.org/pypi/setuptools]
 131
 132 Optional:
 133
 134  * VirtualEnv (python-virtualenv) [http://www.virtualenv.org]
 135
 136 Setup a virtual enviroment (optional)
 137 """""""""""""""""""""""""""""""""""""
 138
 139 With virtualenv users can setup kamaki and Synnefo services in a sandbox
 140 environment.
 141
 142 .. code-block:: console
 143
 144     $ virtualenv kamaki-env
 145     $ source kamaki-env/bin/activate
 146
 147 A more detailed example of using virtual env can be found at the
 148 `snf-image-creator setup guide <http://www.synnefo.org/docs/snf-image-creator/latest/install.html#python-virtual-environment>`_
 149
 150 Install kamaki
 151 """"""""""""""
 152
 153 .. code-block:: console
 154
 155     $ pip install kamaki
 156
 157 Install ansicolors
 158 """"""""""""""""""
 159
 160 The **ansicolors** package is not required for running kamaki, but it is
 161 recommended as a user experience improvement. In specific, ansicolors
 162 adds colors to kamaki responses.
 163
 164 .. code-block:: console
 165
 166     $ pip install ansicolors
 167
 168 Install mock (developers only)
 169 """"""""""""""""""""""""""""""
 170
 171 The **mock** package is needed for running the prepared unit-tests in the
 172 kamaki.clients package. This feature is useful when extending / debugging
 173 kamaki functionality and is aimed to kamaki developers and contributors.
 174 Therefore, users can enjoy the full kamaki user experience without installing
 175 mock.
 176
 177 .. code-block:: console
 178
 179     $ pip install mock
 180
 181 .. warning:: mock version >= 1.X
 182
 183 .. hint:: To activate functional tests in kamaki. enable the preconfigured
 184     *livetest* command group:
 185
 186     .. code-block:: console
 187
 188         $ kamaki config set livetest_cli livetest
 189
 190 Install astakosclient
 191 """""""""""""""""""""
 192
 193 A seperate project called
 194 `astakosclient <https://pypi.python.org/pypi/astakosclient>`_ can be used for
 195 advanced user and service management.
 196
 197 .. code-block:: console
 198
 199     $ pip install astakosclient
 200
 201 .. hint:: To activate astakosclient commands in kamaki, enable the
 202     preconfigured *astakos* command group:
 203
 204     .. code-block:: console
 205
 206         $ kamaki config set astakos_cli astakos
 207
 208 Mac OS X
 209 --------
 210
 211 Kamaki can be installed on Mac OS X systems from source, by following the steps
 212 at :ref:`installing-from-pypi-ref`.
 213
 214 Windows
 215 -------
 216
 217 Kamaki can be installed on Windows by following the pypi method. Installing the
 218 requirements is a bit different than in other systems.
 219
 220 The full process is detailed in the following:
 221
 222 Requirements
 223 ^^^^^^^^^^^^
 224
 225 * Python 2.7 or better (`Official versions <http://www.python.org/getit>`_)
 226
 227 * Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
 228
 229 Users who have already set up and wokring python and setuptools (e.g., for
 230 another project) may skip Python and / or setuptools installation.
 231
 232 Install Python
 233 ^^^^^^^^^^^^^^
 234
 235 Download and run the Windows installer from
 236 `here <http://www.python.org/getit>`_
 237
 238 Users should pick the installer that fits their windows version and machine
 239 architecture.
 240
 241 Add Python to windows path
 242 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 243
 244 The following will allow users to run Python and Python scripts from command
 245 line.
 246
 247 * Select **System** from the Control Panel, select the **Advanced** tab, the
 248     **Environment Variables** button and then find the **PATH** (user or
 249     system) and **edit**
 250
 251 * Without removing existing values, append the following to PATH::
 252
 253     ;C:\Python27;C:\Python27\Scripts
 254
 255 .. note:: Path values are separated by semicolons
 256
 257 .. warning:: In case of a different version, C:\\Python27 should be replaced
 258     with the actual python path in the system
 259
 260 Install setuptools
 261 ^^^^^^^^^^^^^^^^^^
 262
 263 According to the corresponding
 264 `python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools
 265 installer doesn't currently work on 64bit machines.
 266
 267 * Users with 32-bit operating systems should download and run the graphic
 268     installer
 269
 270 * Users with 64-bit machines should download the
 271     `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_ script and
 272     install it from a command shell. In the following example, the script was
 273     downloaded at C:\\Downloads::
 274
 275         C:\> cd Downloads
 276         C:\Downloads\> python ez_setup.py
 277         ...
 278         Installation finished
 279         C:\Downloads\>
 280
 281 Install kamaki
 282 ^^^^^^^^^^^^^^
 283
 284 .. code-block:: console
 285
 286     $ easy_install kamaki