Instructions for the cloudplugfest Madrid, step by step instructions to discover and get up and running with Apache CloudStack in 2 hours.

cloudplugfest

CloudStack at CloudPlugFest Madrid
==================================

These instructions aim to give an introduction to Apache CloudStack. Accessing a production cloud based on CloudStack, getting a feel for it, then using DevCloud2 to run CloudStack locally.

0. Getting your feet wet with http://exoscale.ch
1. Installation of the prerequisites
2. Compiling and installation from source
3. Installation with DevCloud the CloudStack sandbox
4. Using the community packaged repo.

Getting your feet wet with [exoscale.ch](http://exoscale.ch)
============================================================

1. Go to [exoscale.ch](http://exoscale.ch) and click on `free sign-up` in the Open Cloud section
2. Browse the UI identify the `security groups` and `keypairs` sections.
3. Create a rule in your default security group to allow inbound traffic on port 22 (ssh)
4. Create a keypair and store the private key on your machine
5. Start an instance
6. ssh to the instance
7. Inspect the API requests with firebug or dev console of your choice

This cloud is based on CloudStack. It exposes the CloudStack native API. Let's use CloudMonkey the ACS cli.

    pip install cloudmonkey
    cloumonkey

The full documentation for cloudmonkey is on the [wiki](https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI)

    set port 443
    set protocol https
    set path /compute
    set host api.exoscale.ch
    set apikey <yourapikey>
    set secretkey <secretkey>

Explore the ACS native API with CloudMonkey and tab tab....

Prerequisites
=============

In this section we'll look at installing the dependencies you'll need for Apache CloudStack development.
These instructions are for Ubuntu 12.04. On other systems you will need to have git, maven, mysql, openjdk, mkisofs and tomcat/jetty.

First update and upgrade your system:

    apt-get update 
    apt-get upgrade

Install `git` to later clone the CloudStack source code:

    apt-get install git

Install `Maven` to later build CloudStack
  
	apt-get install maven

This should have installed Maven 3.0, check the version number with `mvn --version`

A little bit of Python can be used (e.g simulator), install the Python package management tools:

    apt-get install python-pip python-setuptools

Install `openjdk`. As we're using Linux, OpenJDK is our first choice. 

    apt-get install openjdk-6-jdk

Install `tomcat6`, note that the new version of tomcat on [Ubuntu](http://packages.ubuntu.com/precise/all/tomcat6) is the 6.0.35 version.

    apt-get install tomcat6

Next, we'll install MySQL if it's not already present on the system.

    apt-get install mysql-server

Remember to set the correct `mysql` password in the CloudStack properties file. Mysql should be running but you can check it's status with:

    service mysql status

Finally install `mkisofs` with:
	
    apt-get install genisoimage

Installing from Source
======================

CloudStack uses git for source version control, if you know little about [git](http://book.git-scm.com/) is a good start. Once you have git setup on your machine, pull the source with:

    git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git
	
To build the latest stable release:
    
    git checkout 4.2

To compile Apache CloudStack, go to the cloudstack source folder and run:

    mvn -Pdeveloper,systemvm clean install

If you want to skip the tests add `-DskipTests` to the command above

You will have made sure to set the proper db password in `utils/conf/db.properties`

Deploy the database next:

    mvn -P developer -pl developer -Ddeploydb

Run Apache CloudStack with jetty for testing. Note that `tomcat` maybe be running on port 8080, stop it before you use `jetty`

    mvn -pl :cloud-client-ui jetty:run

Log Into Apache CloudStack:

Open your Web browser and use this URL to connect to CloudStack:

    http://localhost:8080/client/

Replace `localhost` with the IP of your management server if need be.

**Note**: If you have iptables enabled, you may have to open the ports used by CloudStack. Specifically, ports 8080, 8250, and 9090.

You can now start configuring a Zone, playing with the API. Of course we did not setup any infrastructure, there is no storage, no hypervisors...etc

Using DevCloud
==============

Installing from source will only get you to the point of running the management server, it does not get you any hypervisors. With DevCloud you can run at least one hypervisor and add it to your management server the way you would a real physical machine.

[DevCloud](https://cwiki.apache.org/confluence/display/CLOUDSTACK/DevCloud) is the CloudStack sandbox, the standard version is a VirtualBox based image. There is also a KVM based image for it. Here we only show steps with the VirtualBox image. For KVM see the [wiki](https://cwiki.apache.org/confluence/display/CLOUDSTACK/devcloud-kvm).

DevCloud Pre-requisites
-----------------------

1. Install [VirtualBox](http://www.virtualbox.org) on your machine

2. Run VirtualBox and under >Preferences create a *host-only interface* on which you disable the DHCP server

3. Download the DevCloud [image](http://people.apache.org/~bhaisaab/cloudstack/devcloud/devcloud2.ova)
For this workshop, get the image from the USB keys given out.

4. In VirtualBox, under File > Import Appliance import the DevCloud image.

5. Verify the settings under > Settings and check the `enable PAE` option in the processor menu

6. Once the VM has booted try to `ssh` to it with credentials: root/password

    ssh root@192.168.56.10

Adding DevCloud as an Hypervisor
--------------------------------

Picking up from a clean build:

    mvn -Pdeveloper,systemvm clean install
    mvn -P developer -pl developer -Ddeploydb
	
Run the management server:

    mvn -pl :cloud-client-ui jetty:run
	
At this stage install marvin similarly than with the simulator:

    pip install tools/marvin/dist/Marvin-0.1.0.tar.gz

Then you are going to configure CloudStack to use the running DevCloud instance:
	
    cd tools/devcloud
    python ../marvin/marvin/deployDataCenter.py -i devcloud.cfg
	
If you are curious, check the `devcloud.cfg` file and see how the data center is defined: 1 Zone, 1 Pod, 1 Cluster, 1 Host, 1 primary Storage, 1 Secondary Storage, all provided by Devcloud.
	
You can now log in the management server at `http://localhost:8080/client` and start experimenting with the UI or the API.

Do note that the management server is running in your local machine and that DevCloud is used only as a n Hypervisor. You could potentially run the management server within DevCloud as well, or memory granted, run multiple DevClouds.

Other API interfaces
====================

[libcloud](http://libcloud.apache.org), [jclouds](http://jclouds.incubator.apache.org) and [whirr](http://whirr.apache.org) all have good support for CloudStack.

Early OCCI support is being worked on on [github](https://github.com/isaacchiang/rOCCI-server) , we welcome contribution

CIMI might be supported via the StratusLab [CIMI](https://github.com/StratusLab/cimi/) or [deltacloud](http://deltacloud.apache.org)

For the AWS interface, in a dev environment you can run a separate application via jetty:

    mvn -Pawsapi -pl :cloud-awsapi jetty:run

You will then be able to use ec2 command line tools or boto module.

Optional: Using Packages
========================

For non-development environment you can use existing one hosted in a community repo.

To use hosted packages
----------------------

Edit `/etc/apt/sources.list.d/cloudstack.list` and add:

    deb http://cloudstack.apt-get.eu/ubuntu precise 4.1

Replace 4.1 with 4.2 once 4.2 is out

Add the public keys to the trusted keys:

    wget -O - http://cloudstack.apt-get.eu/release.asc|apt-key add -

update your local apt cache

    apt-get update

Install the management server package
	
    apt-get install cloudstack-management


Conclusions
===========

CloudStack is a mostly Java application running with Tomcat and Mysql. It consists of a management server and depending on the hypervisors being used, an agent installed on the hypervisor farm. To complete a Cloud infrastructure however you will also need some Zone wide storage a.k.a Secondary Storage and some Cluster wide storage a.k.a Primary storage. The choice of hypervisor, storage solution and type of Zone (i.e Basic vs. Advanced) will dictate how complex your installation can be. As a quick started, you might want to consider KVM+NFS and a Basic Zone.

If you've run into any problems with this, please ask on the cloudstack-dev [mailing list](/mailing-lists.html).