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