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