X-Git-Url: https://code.grnet.gr/git/kamaki/blobdiff_plain/e3a1d74368c62460f6c968bbfbbc57021135a22a..cfb87e18e5d53efb5c57ff978d36bc8430684a2f:/docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst index e3aa8d5..81ea633 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,92 +1,96 @@ Installation ============ -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. +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 Linux/Unix-like users, it is quite straightforward to install and +have it up and running in all platforms running Python 2.6 or 2.7. * Kamaki repository: `http://code.grnet.gr/git/kamaki `_ -* Synnefo Linux packages: `http://apt.dev.grnet.gr `_, `http://apt2.dev.grnet.gr `_ +* Kamaki at pypi: `http://pypi.python.org/pypi/kamaki `_ -Linux and Unix-like enviroments -------------------------------- +* Synnefo Linux packages: `http://apt.dev.grnet.gr `_ -Ubuntu and Debian packages -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Linux and Unix-like environments +-------------------------------- + +Debian: +^^^^^^^ The following steps describe a command-line approach, but any graphic package manager can be used instead. -Add the following to apt sources list -""""""""""""""""""""""""""""""""""""" +* As root, append the following to */etc/apt/sources.list* :: + + deb http://apt.dev.grnet.gr wheezy/ -As root, append one of the following to */etc/apt/sources.list*: +.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze" +* Make sure the GPG public key for the Synnefo repository is added: -* Debian Stable:: + .. code-block:: console - deb http://apt.dev.grnet.gr/ squeeze main - deb http://apt2.dev.grnet.gr stable/ + $ sudo curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add - -* Ubuntu:: + otherwise *apt-get update* will produce GPG warnings. - deb http://ppa.launchpad.net/grnet/synnefo/ubuntu main - deb-src http://ppa.launchpad.net/grnet/synnefo/ubuntu main +* Update the Debian sources: -where is the system Ubuntu version (e.g. precise) + .. code-block:: console -Update -"""""" + $ sudo apt-get update -* In Debian, make sure the GPG public key for the GRNET dev team is added: +* Install kamaki: .. code-block:: console - $ curl https://dev.grnet.gr/files/apt-grnetdev.pub|apt-key add - + $ sudo apt-get install kamaki - otherwise *apt-get update* will produce GPG warnings. +Ubuntu +^^^^^^ -* In Ubuntu, make sure the correct PPA signing key is installed: +The following steps describe a command-line approach, but any graphic package +manager can be used instead. + +* Let ppa take care of the repository configuration: .. code-block:: console $ sudo apt-get install python-software-properties $ sudo add-apt-repository ppa:grnet/synnefo -Finally: - -.. code-block:: console - - $ sudo apt-get update +* Update the Debian sources: + .. code-block:: console -Install kamaki -"""""""""""""" + $ sudo apt-get update -.. note:: The objpool package is available at synnefo repositories and is automatically installed as a dependency. +* Install kamaki: -.. code-block:: console + .. code-block:: console - $ sudo apt-get install kamaki + $ sudo apt-get install kamaki -Install ansicolors and/or progress (Optional) +Install ansicolors (optional but recommended) """"""""""""""""""""""""""""""""""""""""""""" .. code-block:: console $ sudo apt-get install python-ansicolors - $ sudo apt-get install python-progress -.. _installing-from-source-ref: -Installing from source (git repos.) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _installing-from-pypi-ref: + +Installing from pypi +^^^^^^^^^^^^^^^^^^^^ Requirements """""""""""" Essential: - * Python 2.6 or better [http://www.python.org] + * Python 2.6 or 2.7 [http://www.python.org] * Python setuptools [http://pypi.python.org/pypi/setuptools] Optional: @@ -96,157 +100,111 @@ Optional: Setup a virtual enviroment (optional) """"""""""""""""""""""""""""""""""""" -With virtualenv users can setup kamaki and synnefo services in a sandbox environment. +Use virtualenv to setup kamaki and Synnefo services in a sandbox environment. .. code-block:: console $ virtualenv kamaki-env $ source kamaki-env/bin/activate -A more detailed example of using virtual env can be found at the `snf-image-creator setup guide `_ - -Install objpool (was: snf-common) -""""""""""""""""""""""""""""""""" - -Since 0.6.2, kamaki is based on python-objpool. The objpool package is easy to install from source (even on windows platforms): - -.. code-block:: console - - $ git clone http://code.grnet.gr/git/objpool - $ cd objpool - $ ./setup build install - $ cd - +A more detailed example of using virtual env can be found at the +`snf-image-creator setup guide `_ Install kamaki """""""""""""" -Kamaki can be downloaded from `this location `_, where users can pick the version they prefer and unzip it locally: - .. code-block:: console - $ tar xvfz kamaki-0.6.2.tar.gz - -or it can be downloaded directly from the git repository: - -.. code-block:: console - - $ git clone http://code.grnet.gr/git/kamaki - -and then installed by the setup script: - -.. code-block:: console + $ pip install kamaki - $ cd kamaki - $ ./setup build install - -Install progress and/or ansicolors (optional) -""""""""""""""""""""""""""""""""""""""""""""" - -progress: command-line progress bars (in some commands) +Install ansicolors +"""""""""""""""""" -ansicolors: color kamaki output (can switched on and off in `setup `_) +The **ansicolors** package is not required for running kamaki, but it is +recommended as a user experience improvement. In specific, ansicolors +adds colors to kamaki responses. .. code-block:: console - $ pip install progress $ pip install ansicolors + Mac OS X -------- -Kamaki can be installed on Mac OS X systems from source, by following the steps at :ref:`installing-from-source-ref`. +Kamaki can be installed on Mac OS X systems, by following the steps +at :ref:`installing-from-pypi-ref`. Windows ------- -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 +Kamaki can be installed on Windows by following the pypi method. Installing the +requirements is a bit different than in other systems. + +The full process is detailed in the following: Requirements ^^^^^^^^^^^^ -* Python 2.7 or better (`Official versions `_) - -* Git (download `windows version `_) +* Python 2.7 (`Official versions `_) * Setuptools (`Official versions and workarounds `_) -Installation from source -^^^^^^^^^^^^^^^^^^^^^^^^ +Users who have already set up python and setuptools (e.g., for +another project) may skip Python and / or setuptools installation. -Install python -"""""""""""""" +Install Python +^^^^^^^^^^^^^^ -Download and run the Windows installer from `here `_ +Download and run the Windows installer from +`here `_ -Users should pick the installer that fits their windows version and architecture. +Users should pick the installer that fits their windows version and machine +architecture. -Add python to windows path -"""""""""""""""""""""""""" +Add Python to windows path +^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following will allow users to run python and python scripts from command line. +The following will allow users to run Python and Python scripts from command +line. -* Select **System** from the Control Panel, select the **Advanced** tab, the **Environment Variables** button and then find the **PATH** (user or system) and **edit** +* Select **System** from the Control Panel, select the **Advanced** tab, the + **Environment Variables** button and then find the **PATH** (user or + system) and **edit** * Without removing existing values, append the following to PATH:: - C:\Python;C:\Python\Scripts + ;C:\Python27;C:\Python27\Scripts .. note:: Path values are separated by semicolons -.. warning:: C:\\Python should be replaced with the actual python path in the system, e.g. C:\\Python27 +.. warning:: In case of a different version, C:\\Python27 should be replaced + with the actual python path in the system Install setuptools -"""""""""""""""""" - -According to the corresponding `python org page `_, the setuptools installer doesn't currently work on 64bit machines. - -* Users with 32-bit operating systems should download and run the graphic installer +^^^^^^^^^^^^^^^^^^ -* Users with 64-bit machines should download the `ez_setup.py `_ script and install it from a command shell. In the following example, the script was downloaded at C:\\Downloads:: +According to the corresponding +`python org page `_, the setuptools +installer doesn't currently work on 64bit machines. - C:\> cd Downloads - C:\Downloads\> python ez_setup.py - ... - Installation finished - C:\Downloads\> +* Users with 32-bit platforms should download and run the graphic + installer -Install GIT -""""""""""" +* Users with 64-bit platforms should download the + `ez_setup.py `_ script and + install it from a command shell. In the following example, the script was + downloaded at C:\\Downloads:: -`Download GIT `_ 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. - -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. + C:\> cd Downloads + C:\Downloads\> python ez_setup.py + ... + Installation finished + C:\Downloads\> Install kamaki -"""""""""""""" +^^^^^^^^^^^^^^ -* Run the GIT standalone shell - -* Enter the location where kamaki will be installed, e.g. **C:\\** - - .. code-block:: console - - $ cd /c/ - -* Download source from GRNET repository - - .. code-block:: console - - $ git clone http://code.grnet.gr/git/kamaki - Cloning into 'kamaki'... - Receiving objects: ... - Resolving Deltas: ... - -* Enter source and install kamaki - - .. code-block:: console - - $ cd kamaki - $ python setup.py install - running install - ... - Finished processing dependencies for kamaki==0.6.2 - -.. warning:: kamaki version should be 0.6.2 or better, otherwise it will not function. Users can test that by running:: +.. code-block:: console - $ kamaki --version + $ easy_install kamaki