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