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