.. _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.