Commit 28dd8a05 authored by Stavros Sachtouris's avatar Stavros Sachtouris

Update general information and setup instructions

Refs grnet/kamaki#49
parent 19522a57
......@@ -123,13 +123,13 @@ master_doc = 'index'
# General information about the project.
project = u'Kamaki'
copyright = u'2013, GRNET'
copyright = u'2014, GRNET'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.12'
version = '0.13'
# The full version, including alpha/beta/rc tags.
try:
......
......@@ -16,17 +16,15 @@ have it up and running in all platforms running Python 2.6 or 2.7.
Linux and Unix-like environments
--------------------------------
Debian:
^^^^^^^
Debian
^^^^^^
The following steps describe a command-line approach, but any graphic package manager can be used instead.
For Debian 7.0 (wheezy):
* As root, append the following to */etc/apt/sources.list* ::
deb http://apt.dev.grnet.gr wheezy/
.. warning:: Debian Squeeze users may replace "wheezy" with "squeeze"
* Make sure the GPG public key for the Synnefo repository is added:
.. code-block:: console
......@@ -35,99 +33,108 @@ The following steps describe a command-line approach, but any graphic package ma
otherwise *apt-get update* will produce GPG warnings.
* Update the Debian sources:
* Update and install:
.. code-block:: console
$ sudo apt-get update
$ sudo apt-get install kamaki
* Install kamaki:
Terminal colors (optional but recommended)
""""""""""""""""""""""""""""""""""""""""""
.. code-block:: console
The "python-ansicolors" package enables colorful terminal outputs.
$ sudo apt-get install kamaki
E.g., in Debian:
Ubuntu
^^^^^^
The following steps describe a command-line approach, but any graphic package
manager can be used instead.
.. code-block:: console
* Let ppa take care of the repository configuration:
$ sudo apt-get install python-ansicolors
.. code-block:: console
After the installation, tell kamaki to use the feature
$ sudo apt-get install python-software-properties
$ sudo add-apt-repository ppa:grnet/synnefo
.. code-block:: console
* Update the Debian sources:
$ kamaki config set colors on
.. code-block:: console
Unit tests (developers)
"""""""""""""""""""""""
$ sudo apt-get update
Install the "python-mock" package to make unit tests work (developers only).
* Install kamaki:
.. code-block:: console
.. code-block:: console
$ sudo apt-get install python-mock
$ sudo apt-get install kamaki
Ubuntu
^^^^^^
Install ansicolors (optional but recommended)
"""""""""""""""""""""""""""""""""""""""""""""
For Ubuntu 12.04 LTS, 12.10 and 13.04:
.. code-block:: console
$ sudo apt-get install python-ansicolors
$ sudo apt-get install python-software-properties
$ sudo add-apt-repository ppa:grnet/synnefo
$ sudo apt-get update
$ sudo apt-get install kamaki
Fedora
^^^^^^
.. _installing-from-pypi-ref:
For Fedora 17:
Installing from pypi
^^^^^^^^^^^^^^^^^^^^
.. code-block:: console
Requirements
""""""""""""
$ cd /etc/yum.repos.d
$ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/Fedora_17/home:GRNET:synnefo.repo
$ yum install kamaki
Essential:
CentOS
^^^^^^
* Python 2.6 or 2.7 [http://www.python.org]
* Python setuptools [http://pypi.python.org/pypi/setuptools]
For CentOS 6:
Optional:
.. code-block:: console
* VirtualEnv (python-virtualenv) [http://www.virtualenv.org]
$ cd /etc/yum.repos.d
$ wget http://download.opensuse.org/repositories/home:/GRNET:/synnefo/CentOS_CentOS-6/home:GRNET:synnefo.repo
$ yum install kamaki
Setup a virtual enviroment (optional)
"""""""""""""""""""""""""""""""""""""
OpenSUSE
^^^^^^^^
Use virtualenv to setup kamaki and Synnefo services in a sandbox environment.
For OpenSUSE 12.3:
.. code-block:: console
$ virtualenv kamaki-env
$ source kamaki-env/bin/activate
$ zypper ar -f http://download.opensuse.org/repositories/home:/GRNET:/synnefo/openSUSE_12.3/home:GRNET:synnefo.repo
$ zypper in kamaki
A more detailed example of using virtual env can be found at the
`snf-image-creator setup guide <http://www.synnefo.org/docs/snf-image-creator/latest/install.html#python-virtual-environment>`_
Install kamaki
""""""""""""""
.. _installing-from-pypi-ref:
Installing from pypi
--------------------
Requirements:
* Python 2.7 [http://www.python.org]
* Python setuptools [http://pypi.python.org/pypi/setuptools]
Installation:
.. code-block:: console
$ pip install kamaki
Install ansicolors
""""""""""""""""""
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.
Optional packages:
The ansicolors package enables terminal output coloring. The mock package
allows unit testing while hacking the code.
.. code-block:: console
$ pip install ansicolors
$ pip install mock
Mac OS X
--------
......@@ -141,29 +148,22 @@ 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
^^^^^^^^^^^^
**Requirements**
* Python 2.7 (`Official versions <http://www.python.org/download>`_)
* Setuptools (`Official versions and workarounds <http://pypi.python.org/pypi/setuptools>`_)
Users who have already set up python and setuptools (e.g., for
another project) may skip Python and / or setuptools installation.
Install Python
^^^^^^^^^^^^^^
Download and run the Windows installer from
`here <http://www.python.org/download>`_
.. note:: Skip this step if python 2.7 is already installed
Users should pick the installer that fits their windows version and machine
architecture.
Download and run the Windows installer from
`the download page <http://www.python.org/download>`_
pick the one that fits your windows version and 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.
......@@ -181,20 +181,18 @@ line.
.. warning:: In case of a different version, C:\\Python27 should be replaced
with the actual python path in the system
Install setuptools
Install Setuptools
^^^^^^^^^^^^^^^^^^
According to the corresponding
`python org page <http://pypi.python.org/pypi/setuptools>`_, the setuptools
installer doesn't currently work on 64bit machines.
.. note:: Skip this step if setuptools are already installed
* Users with 32-bit platforms should download and run the graphic
installer
See `here <http://pypi.python.org/pypi/setuptools>`_ for installation
instructions.
* Users with 64-bit platforms should download the
`ez_setup.py <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_
script and install it from a command shell. In the following example, the
script was downloaded at C:\\Downloads::
.. note:: Users with 64-bit platforms should download the
`ez_setup.py <https://bootstrap.pypa.io/ez_setup.py>`_ script and install
it from a command shell. In the following example, the script was
downloaded at C:\\Downloads::
C:\> cd Downloads
C:\Downloads\> python ez_setup.py
......
......@@ -49,8 +49,8 @@ command-line tool for managing a local or remote Synnefo deployment.
* by third-party `Synnefo` deployers for testing and debugging their setup
* as an API library for other components in the Synnefo universe ((`burnin`,
`image-creator`) or external applications
* as an API library for Synnefo-related components (`burnin`, `image-creator`)
or external applications
Community & Support
-------------------
......
This diff is collapsed.
......@@ -3,7 +3,7 @@ Usage
Kamaki features commands of the form::
[kamaki] <object> <action> [identifier(s)] <non-positional arguments>
kamaki <object> <action> [identifier(s)] <non-positional arguments>
e.g.,
kamaki user info --username=user@example.com
......@@ -24,14 +24,12 @@ interactive shell:
[kamaki]: user info
... RESULTS ...
In the later, the term "one-command" will be user to refer to running kamaki
commands from host shell, while the term "shell" will refer to the kamaki's own
interactive shell
In the following, the term "one-command" refer to running kamaki commands from
host shell, while the term "shell" will refer to the interactive shell.
.. note:: This section refers to the kamaki CLI. Developers and people who write
scripts, should rather use the the
`Clients lib <developers/code.html#the-clients-api>`_ instead of the kamaki
CLI.
`Clients library <developers/code.html#the-clients-api>`_ instead.
Quick Setup
-----------
......@@ -44,13 +42,12 @@ As rule of the thump, it is enough to set a cloud authentication URL and TOKEN:
.. code-block:: console
:emphasize-lines: 1
Example 1.1: Set authentication URL, user token for cloud alias "default"
Example 1.1: Set authentication URL, user token for cloud alias CLOUD_NAME
$ kamaki config set cloud.default.url <authentication URL>
$ kamaki config set cloud.default.token myt0k3n==
$ kamaki config set cloud.CLOUD_NAME.url <authentication URL>
$ kamaki config set cloud.CLOUD_NAME.token myt0k3n==
.. note:: The term *default* can be replaced by any arbitary term chosen by
the user.
.. note:: The term CLOUD_NAME is arbitrary and can be chosen by the user
Shell vs one-command
--------------------
......@@ -62,10 +59,9 @@ implementation. However, there are some minor differences.
In favor of interactive shell:
* shorter commands (context switching)
* shorter commands
* tab completion for commands (if supported by host shell)
* kamaki-specific history with ↑ or ↓ keys (if supported by host shell)
* re-run old commands with /history
In favor of one-command:
......@@ -83,7 +79,7 @@ To use kamaki as a shell, run:
$ kamaki-shell
* with any kind of '-' prefixed arguments, except '-h', '--help', '-V',
* with any kind of '-' prefixed arguments, except '-h', '- - help', '-V',
'- - version'.
.. code-block:: console
......@@ -95,16 +91,16 @@ To use kamaki as a shell, run:
Example 2.2.3: Run kamaki shell so as to use a specific cloud
$ kamaki-shell --cloud=my_demo_cloud
$ kamaki-shell --cloud=example_cloud
Example 2.2.4: Run kamaki shell with verbosity (shows HTTP requests)
Example 2.2.4: Run kamaki shell with verbosity (prints HTTP communication)
$ kamaki-shell -v
.. note:: Valid arguments can be combined e.g., it is ok to run a shell with
verbosity and a specific cloud::
.. note:: Valid arguments can be combined e.g., to run a shell with verbosity
and a specific cloud::
$ kamaki-shell -v --cloud=my_demo_cloud
$ kamaki-shell -v --cloud=example_cloud
Run as one-command
^^^^^^^^^^^^^^^^^^
......@@ -113,9 +109,6 @@ To use kamaki as an one-command tool, run:
* with the '-h' or '--help' arguments (help for kamaki one-command)
.. code-block:: console
:emphasize-lines: 1
Example 2.3.1: Kamaki help
$kamaki -h
......@@ -124,7 +117,7 @@ To use kamaki as an one-command tool, run:
.. code-block:: console
:emphasize-lines: 1
Example 2.3.2: List servers managed by user
Example 2.3.2: List virtual servers
$ kamaki server list
......
......@@ -341,7 +341,7 @@ class Config(RawConfigParser):
def get_cloud(self, cloud, option):
"""
:param cloud: (str) cloud alias
:param cloud: (str) cloud name
:param option: (str) option in cloud section
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment