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 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.
   5
   6
   7 * Kamaki repository: `http://code.grnet.gr/git/kamaki <http://code.grnet.gr/git/kamaki>`_
   8
   9 * Synnefo Linux packages: `http://apt.dev.grnet.gr <http://apt.dev.grnet.gr>`_, `http://apt2.dev.grnet.gr <http://apt2.dev.grnet.gr>`_
  10
  11 Linux and Unix-like enviroments
  12 -------------------------------
  13
  14 Ubuntu and Debian packages
  15 ^^^^^^^^^^^^^^^^^^^^^^^^^^
  16
  17 The following steps describe a command-line approach, but any graphic package manager can be used instead.
  18
  19 Add the following to apt sources list
  20 """""""""""""""""""""""""""""""""""""
  21
  22 As root, append one of the following to */etc/apt/sources.list*:
  23
  24
  25 * Debian Stable (kamaki 0.6.2)::
  26
  27     deb http://apt.dev.grnet.gr/ squeeze main
  28     deb http://apt2.dev.grnet.gr stable/
  29
  30 * Ubuntu (kamaki 0.6.2)::
  31
  32     deb http://apt.dev.grnet.gr/ precise main
  33
  34
  35 Update
  36 """"""
  37
  38 .. note:: make sure the GPG public key for the GRNET dev team is added:
  39
  40     .. code-block:: console
  41
  42         $ curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add -
  43
  44     otherwise *apt-get update* will produce GPG warnings.
  45
  46 .. code-block:: console
  47
  48     $ sudo apt-get update
  49
  50
  51 Install kamaki
  52 """"""""""""""
  53
  54 .. note:: **versions 0.6.0 - 0.6.1 only:**
  55
  56     The *snf-common* package (available at synnefo apt repository) will be automatically installed as a dependency.
  57
  58 .. note:: **versions 0.6.2 and on:**
  59
  60     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.
  61
  62 .. code-block:: console
  63
  64     $ sudo apt-get install kamaki
  65
  66 Install ansicolors and/or progress (Optional)
  67 """""""""""""""""""""""""""""""""""""""""""""
  68
  69 .. code-block:: console
  70
  71     $ sudo apt-get install python-ansicolors
  72     $ sudo apt-get install python-progress
  73
  74 .. _installing-from-source-ref:
  75
  76 Installing from source (git repos.)
  77 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  78
  79 Requirements
  80 """"""""""""
  81
  82 Essential:
  83
  84  * Python 2.6 or better [http://www.python.org]
  85  * Python setuptools [http://pypi.python.org/pypi/setuptools]
  86
  87 Optional:
  88
  89  * VirtualEnv (python-virtualenv) [http://www.virtualenv.org]
  90
  91 Setup a virtual enviroment (optional)
  92 """""""""""""""""""""""""""""""""""""
  93
  94 With virtualenv users can setup kamaki and synnefo services in a sandbox environment.
  95
  96 .. code-block:: console
  97
  98     $ virtualenv kamaki-env
  99     $ source kamaki-env/bin/activate
 100
 101 A more detailed example of using virtual env can be found at the `snf-image-creator setup guide <http://docs.dev.grnet.gr/snf-image-creator/latest/install.html#python-virtual-environment>`_
 102
 103 Install objpool (was: snf-common)
 104 """""""""""""""""""""""""""""""""
 105
 106 .. note:: **versions 0.6.0 - 0.6.1 only**
 107
 108     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:
 109
 110     .. code-block:: console
 111
 112         $ git clone http://code.grnet.gr/git/synnefo
 113         $ cd synnefo/snf-common
 114         $ ./setup build install
 115         $ cd -
 116
 117 **Version 0.6.2 and on:**
 118
 119 Since 0.6.2, kamaki is based on python-objpool. The objpool package is easy to install from source (even on windows platforms):
 120
 121 .. code-block:: console
 122
 123     $ git clone http://code.grnet.gr/git/objpool
 124     $ cd objpool
 125     $ ./setup build install
 126     $ cd -
 127
 128 Install kamaki
 129 """"""""""""""
 130
 131 Kamaki can be downloaded from `here <https://code.grnet.gr/projects/kamaki/files>`_, where users can pick the version they prefer and unzip it locally:
 132
 133 .. code-block:: console
 134
 135     $ tar xvfz kamaki-0.6.2.tar.gz
 136
 137 or it can be downloaded directly from the git repository:
 138
 139 .. code-block:: console
 140
 141     $ git clone http://code.grnet.gr/git/kamaki
 142
 143 and then installed by the setup script:
 144
 145 .. code-block:: console
 146     $ cd kamaki
 147     $ ./setup build install
 148
 149 Install progress and/or ansicolors (optional)
 150 """""""""""""""""""""""""""""""""""""""""""""
 151
 152 progress: command-line progress bars (in some commands)
 153
 154 ansicolors: color kamaki output (can switched on and off in `setup <setup.html>`_)
 155
 156 .. code-block:: console
 157
 158     $ pip install progress
 159     $ pip install ansicolors
 160
 161 Mac OS X
 162 --------
 163
 164 Kamaki can be installed on Mac OS X systems from source, by following the steps at :ref:`installing-from-source-ref`.
 165
 166 Windows
 167 -------
 168
 169 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
 170
 171 Requirements
 172 ^^^^^^^^^^^^
 173
 174 * Python 2.7 or better (`Official versions <http://www.python.org/getit>`_)
 175
 176 * Git (download `windows version <http://git-scm.com/download/win>`_)
 177
 178 * Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
 179
 180 Installation from source
 181 ^^^^^^^^^^^^^^^^^^^^^^^^
 182
 183 Install python
 184 """"""""""""""
 185
 186 Download and run the Windows installer from `here <http://www.python.org/getit>`_
 187
 188 Users should pick the installer that fits their windows version and architecture.
 189
 190 Add python to windows path
 191 """"""""""""""""""""""""""
 192
 193 The following will allow users to run python and python scripts from command line.
 194
 195 * Select **System** from the Control Panel, select the **Advanced** tab, the **Environment Variables** button and then find the **PATH** (user or system) and **edit**
 196
 197 * Without removing existing values, append the following to PATH::
 198
 199     C:\Python;C:\Python\Scripts
 200
 201 .. note:: Path values are separated by semicolons
 202
 203 .. warning:: C:\\Python should be replaced with the actual python path in the system, e.g. C:\\Python27
 204
 205 Install setuptools
 206 """"""""""""""""""
 207
 208 According to the corresponding `python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools installer doesn't currently work on 64bit machines.
 209
 210 * Users with 32-bit operating systems should download and run the graphic installer
 211
 212 * Users with 64-bit machines should download the `ez_setup.py <http://peak.telecommunity.com/dist/ez_setup.py>`_ script and install it from a command shell. In the following example, the script was downloaded at C:\\Downloads::
 213
 214     C:\> cd Downloads
 215     C:\Downloads\> python ez_setup.py
 216     ...
 217     Installation finished
 218     C:\Downloads\>
 219
 220 Install GIT
 221 """""""""""
 222
 223 `Download GIT <http://git-scm.com/download/win>`_ 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.
 224
 225 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.
 226
 227 Install kamaki
 228 """"""""""""""
 229
 230 * Run the GIT standalone shell
 231
 232 * Enter the location where kamaki will be installed, e.g. **C:\\**
 233
 234     .. code-block:: console
 235
 236         $ cd /c/
 237
 238 * Download source from GRNET repository
 239
 240     .. code-block:: console
 241
 242         $ git clone http://code.grnet.gr/git/kamaki
 243         Cloning into 'kamaki'...
 244         Receiving objects: ...
 245         Resolving Deltas: ...
 246
 247 * Enter source and install kamaki
 248
 249     .. code-block:: console
 250
 251         $ cd kamaki
 252         $ python setup.py install
 253         running install
 254         ...
 255         Finished processing dependencies for kamaki==0.6.2
 256
 257 .. warning:: kamaki version should be 0.6.2 or better, otherwise it will not function. Users can test that by running::
 258
 259     $ kamaki --version