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 .. _installing-from-pypi-ref:
 102
 103 Installing from pypi
 104 ^^^^^^^^^^^^^^^^^^^^
 105
 106 Requirements
 107 """"""""""""
 108
 109 Essential:
 110
 111  * Python 2.6 or 2.7 [http://www.python.org]
 112  * Python setuptools [http://pypi.python.org/pypi/setuptools]
 113
 114 Optional:
 115
 116  * VirtualEnv (python-virtualenv) [http://www.virtualenv.org]
 117
 118 Setup a virtual enviroment (optional)
 119 """""""""""""""""""""""""""""""""""""
 120
 121 Use virtualenv to setup kamaki and Synnefo services in a sandbox
 122 environment.
 123
 124 .. code-block:: console
 125
 126     $ virtualenv kamaki-env
 127     $ source kamaki-env/bin/activate
 128
 129 A more detailed example of using virtual env can be found at the
 130 `snf-image-creator setup guide <http://www.synnefo.org/docs/snf-image-creator/latest/install.html#python-virtual-environment>`_
 131
 132 Install kamaki
 133 """"""""""""""
 134
 135 .. code-block:: console
 136
 137     $ pip install kamaki
 138
 139 Install ansicolors
 140 """"""""""""""""""
 141
 142 The **ansicolors** package is not required for running kamaki, but it is
 143 recommended as a user experience improvement. In specific, ansicolors
 144 adds colors to kamaki responses.
 145
 146 .. code-block:: console
 147
 148     $ pip install ansicolors
 149
 150 Install mock (developers only)
 151 """"""""""""""""""""""""""""""
 152
 153 The **mock** package is needed for running the prepared unit-tests in the
 154 kamaki.clients package. This feature is useful when extending / debugging
 155 kamaki functionality and is aimed to kamaki developers and contributors.
 156 Therefore, users can enjoy the full kamaki user experience without installing
 157 mock.
 158
 159 .. code-block:: console
 160
 161     $ pip install mock
 162
 163 .. warning:: mock version >= 1.X
 164
 165 .. hint:: To activate functional tests in kamaki. enable the preconfigured
 166     *livetest* command group:
 167
 168     .. code-block:: console
 169
 170         $ kamaki config set livetest_cli livetest
 171
 172
 173 Mac OS X
 174 --------
 175
 176 Kamaki can be installed on Mac OS X systems, by following the steps
 177 at :ref:`installing-from-pypi-ref`.
 178
 179 Windows
 180 -------
 181
 182 Kamaki can be installed on Windows by following the pypi method. Installing the
 183 requirements is a bit different than in other systems.
 184
 185 The full process is detailed in the following:
 186
 187 Requirements
 188 ^^^^^^^^^^^^
 189
 190 * Python 2.7 or better (`Official versions <http://www.python.org/getit>`_)
 191
 192 * Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
 193
 194 Users who have already set up python and setuptools (e.g., for
 195 another project) may skip Python and / or setuptools installation.
 196
 197 Install Python
 198 ^^^^^^^^^^^^^^
 199
 200 Download and run the Windows installer from
 201 `here <http://www.python.org/getit>`_
 202
 203 Users should pick the installer that fits their windows version and machine
 204 architecture.
 205
 206 Add Python to windows path
 207 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 208
 209 The following will allow users to run Python and Python scripts from command
 210 line.
 211
 212 * Select **System** from the Control Panel, select the **Advanced** tab, the
 213     **Environment Variables** button and then find the **PATH** (user or
 214     system) and **edit**
 215
 216 * Without removing existing values, append the following to PATH::
 217
 218     ;C:\Python27;C:\Python27\Scripts
 219
 220 .. note:: Path values are separated by semicolons
 221
 222 .. warning:: In case of a different version, C:\\Python27 should be replaced
 223     with the actual python path in the system
 224
 225 Install setuptools
 226 ^^^^^^^^^^^^^^^^^^
 227
 228 According to the corresponding
 229 `python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools
 230 installer doesn't currently work on 64bit machines.
 231
 232 * Users with 32-bit platforms should download and run the graphic
 233     installer
 234
 235 * Users with 64-bit platforms should download the
 236     `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_ script and
 237     install it from a command shell. In the following example, the script was
 238     downloaded at C:\\Downloads::
 239
 240         C:\> cd Downloads
 241         C:\Downloads\> python ez_setup.py
 242         ...
 243         Installation finished
 244         C:\Downloads\>
 245
 246 Install kamaki
 247 ^^^^^^^^^^^^^^
 248
 249 .. code-block:: console
 250
 251     $ easy_install kamaki