.. _getting-started:
Getting started
===============
Introduction
------------
This tutorial gets you started with Ensemble. A prerequisite is the
access credentials to a dedicated computing environment such as what
is offered by a virtualized cloud hosting environment.
Ensemble has been designed for environments which can provide a
new machine with an Ubuntu cloud operating system image
on-demand. This includes services such as `Amazon EC2
`_ or `RackSpace
`_.
It's also required that the environment provides a permanent storage
facility such as `Amazon S3 `_.
For the moment, though, the only environment supported is EC2.
Running from trunk
------------------
To run Ensemble, you will need the following dependencies installed:
* zookeeper
* txzookeeper
* txaws
On a modern Ubuntu Linux system execute::
$ sudo apt-get install python-zookeeper python-txaws
You will also need Python 2.6 or better.
To get Ensemble and run it from trunk, do::
$ bzr branch lp:ensemble
$ cd ensemble
$ export PYTHONPATH=$PWD:$PYTHONPATH
$ bin/ensemble
Note that you must configure your environment before Ensemble will
be of any use. See below.
Configuring your environment
----------------------------
Run the command-line utility with no arguments to create a sample
environment::
$ bin/ensemble
This will create the file ``~/.ensemble/environments.yaml``, which will look
something like this::
ensemble: environments
environments:
sample:
type: ec2
control-bucket: ensemble-faefb490d69a41f0a3616a4808e0766b
admin-secret: 81a1e7429e6847c4941fda7591246594
Which is a sample environment configured to run with EC2 machines and S3
permanent storage. To make this environment actually useful, you will need
to tell Ensemble about an AWS access key and secret key. To do this, you
can either set the ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY``
environment variables (as usual for other EC2 tools) or you can add
``access-key`` and ``secret-key`` options to your ``environments.yaml``.
For example::
ensemble: environments
environments:
sample:
type: ec2
access-key: YOUR-ACCESS-KEY-GOES-HERE
secret-key: YOUR-SECRET-KEY-GOES-HERE
control-bucket: ensemble-faefb490d69a41f0a3616a4808e0766b
admin-secret: 81a1e7429e6847c4941fda7591246594
The S3 bucket does not need to exist already.
.. note::
If you already have an AWS account, you can determine your access key by
visiting http://aws.amazon.com/account, clicking "Security Credentials" and
then clicking "Access Credentials". You'll be taken to a table that lists
your access keys and has a "show" link for each access key that will reveal
the associated secret key.