Introduction

This document intends to describe how to deploy AppScale 1.2 over a Eucalyptus installation. Please leave comments as needed if you run into problems with these instructions.

These instructions assume that you have root/sudo access.

System Requirements

In order to deploy AppScale via Eucalyptus, you will need the following:

• A Eucalyptus 1.52 cloud running on 64-bit machines only
• Install the EC2-tools from the two links at the top of this page. This is the version of the tools that we currently support. Unpackage both files and move the files from the bin and lib directories to a fixed location (combine the bin and lib dirs into one under an ec2-tools directory), e.g. /usr/local/ec2-tools. Put the bin directory in your path, e.g. export PATH=${PATH}:/usr/local/ec2-tools/bin and set EC2_HOME to the fixed location, e.g. export EC2_HOME=/usr/local/ec2-tools.
• Administrator credentials to the aforementioned cloud (that is, the private key and certificate you receive from logging into your cloud as admin).

Again note that having 64-bit machines is a must, since the kernel image and ramdisk image that we provide are 64-bit, and thus are incompatible with 32-bit systems. To see if you have a 64-bit machine, in Linux, type cat /proc/cpuinfo |grep lm; if nothing prints out, you are on a 32-bit machine (lm stands for longmode and appears in the FLAGS field on 64-bit machines.

Uploading the Image to Eucalyptus

At this point, take the given Xen image and upload it to Eucalyptus. This process will yield a Eucalyptus Machine Image number (emi). If you are not familiar with this process, this page outlines the details.

Setting up the AppScale Tools

Install and setup the AppScale Tools using the instructions described in the AppScale Tools page.

Running a Sample Application

Now onto running a sample application! We bundle a number of tested applications that work on AppScale with the appscale-tools, and for this example we will be using the guestbook application. This application allows users to leave comments on a page and view them later. It sorts the comments and shows only the ten most recent comments.

To run the guestbook application, do the following:

-- copy guestbook.tar.gz from /usr/local/appscale-tools-1.1/sample_apps to your local directory
appscale-run-instances --file guestbook.tar.gz --machine emi-XXXXXX --table hbase

For example, using the AppScale emi from above we execute

appscale-run-instances --file guestbook.tar.gz --machine emi-CEDD1083 --table hbase Alternatively, you can start AppScale first with appscale-run-instances --machine emi-8E310F25 and then upload GAE apps via appscale-upload-app --file guestbook.tar.gz. We assume that you use the former in this example.

The AppScale startup process can take a while (~15 minutes) because Eucalyptus must copy the images from the cache to a local working instance directory. The AppScale tools will wait a maximum of two hours for your images to start and will fail if it cannot secure the needed number of virtual machines within that window of time. If that does happen, you are advised to read the Troubleshooting page for potential solutions.

appscale-run-instances creates four instances of the AppScale virtual machine image (emi). Once they are started, you will be prompted to create an administrator account and a password. The admin account can be any email address and the password can be any printable characters, although it must be at least six characters long. You should see output similar to the following:

root@cpp:~# appscale-run-instances --file guestbook.tar.gz --machine emi-CEF81080 --table hbase
Run instances message sent successfully. Waiting for the image to start up.
[Tue Sep 08 11:48:29 -0700 2009] 3599.999982 seconds left until timeout...
[Tue Sep 08 11:50:31 -0700 2009] 3478.259612 seconds left until timeout...
[Tue Sep 08 11:52:33 -0700 2009] 3356.411676 seconds left until timeout...
Please wait for your instance to complete the bootup process.
Head node successfully created at 128.111.55.225. It is now starting up hbase via the command line arguments given.
Killing and starting server at 128.111.55.225
Please wait for the controller to finish pre-processing tasks.

This AppScale instance is linked to an e-mail address giving it administrator privileges.
Enter your desired administrator e-mail address: foo@goo.boo
Please repeat your e-mail address to verify: foo@goo.boo

The new administrator password must be at least six characters long and can include non-alphanumeric characters.
Enter your new password: 
Enter again to verify: 
Please wait for AppScale to prepare your machines for use.Spawning up 3 virtual machines
Copying over needed files and starting the AppController on the other VMs
Setting up database configuration files
Preparing HBase for use on the slaves
Done starting up AppScale, now in heartbeat mode

Your user account has been created successfully.
Uploading guestbook...
We have reserved the name guestbook for your application.
guestbook was uploaded successfully.
Please wait for your app to start up.

Your app can be reached at the following URL: http://128.111.55.225/apps/guestbook
The status of your AppScale instance is at the following URL: http://128.111.55.225/status

Note: Uploading the first application takes a while. An alternative is to start AppScale without an application, then upload applications using the appscale-upload-app tool -- each app takes only a minute or so. The 10-15 minute wait is for all of the instances to deploy and achieve a consistent state.

Note: The first time a running application uses the database, AppScale initializes the database. This first access can take some time; subsequent accesses however will be significantly faster.

Access your application via the provided specified the output (here, it is http://128.111.55.225/apps/guestbook).

Seeing the Status of Your AppScale Instances

Once appscale-run-instances completes and your application has been deployed within AppScale, you can verify its status in two ways. First, you can use the cloud status URL returned by appscale-run-instances (http://128.111.55.225/status above) or use the command-line tool appscale-describe-instances. Continuing with our guestbook example, running appscale-describe-instances yields the following output:

root@cpp:~# appscale-describe-instances
Status of node at 128.111.55.225:
    Currently using 1.7 Percent CPU and 40.45 Percent Memory
    Database is at 128.111.55.225
    Hosting the following apps: guestbook
    Current State: Done starting up AppScale, now in heartbeat mode
Status of node at 128.111.55.205:
    Currently using 0.9 Percent CPU and 28.03 Percent Memory
    Database is at 128.111.55.225
    Hosting the following apps: guestbook
    Current State: Preparing to run AppEngine apps if needed
Status of node at 128.111.55.211:
    Currently using 0.9 Percent CPU and 28.24 Percent Memory
    Database is at 128.111.55.225
    Hosting the following apps: guestbook
    Current State: Preparing to run AppEngine apps if needed
Status of node at 128.111.55.226:
    Currently using 0.9 Percent CPU and 28.25 Percent Memory
    Database is at 128.111.55.225
    Hosting the following apps: guestbook
    Current State: Preparing to run AppEngine apps if needed

In this example, the database is hosted on 128.111.55.225 while the other nodes are hosting the guestbook application. 128.111.55.225 shows that it is hosting guestbook as well since it has uploaded its tar file into the running AppScale instance, and knows to redirect requests to it to the other nodes as needed. Note that you will see different CPU and memory usage percents based on the amount of virtual memory that you have given your instances.

Terminating Your AppScale Instances

If you want to free up the instances created by AppScale, you can use the provided appscale-terminate-instances tool. Note that this tool does kill all instances running on your Eucalyptus cloud, so if you have other virtual machines running on Eucalyptus unrelated to AppScale you should terminate them manually and not use this tool. It is used in the same way as the other tools and running it yields output similar to this:

root@cpp:~# appscale-terminate-instances
About to terminate instances spawned via ec2 with keyname 'appscale'...
INSTANCE        i-405208D4      running shutting-down
INSTANCE        i-4F1F073B      running shutting-down
INSTANCE        i-4FFC092A      running shutting-down
INSTANCE        i-537D0921      running shutting-down
Terminated AppScale across 4 boxes.

You can verify that your AppScale instance was terminated by using appscale-describe-instances one last time (the provided keyname is AppScale's default keyname):

root@cpp:~# appscale-describe-instances
An AppScale instance is not currently running with the provided keyname, "appscale".

Now that you've successfully deployed AppScale, check out the advanced features to see how you can deviate from this "standard run" and how AppScale differs in these situations.