Elastic Beanstalk Tutorial

Overview

In this tutorial, you will be installing and running a TravelLog (aka blog) application using the AWS Elastic Beanstalk service. The Travel Log application runs on EC2, stores original and thumbnail images in Amazon S3, tracks information about each photo and log entry in Amazon SimpleDB, and sends email notifications using the Amazon Simple Notification Service.

Background on Elastic Beanstalk

"AWS Elastic Beanstalk is an easy way for you to quickly deploy and manage applications in the AWS cloud. You simply upload your application, and Elastic Beanstalk automatically handles the deployment details of capacity provisioning, load balancing, auto-scaling, and application health monitoring." ~ Amazon Marketing Literature

The initial release of Elastic Beanstalk is built for Java developers using the (popular) Apache Tomcat software stack. To deploy Java applications:

Create your application as you normally would using any editor or IDE (e.g. Eclipse).
Package your deployable code into a standard Java Web Application Archive (WAR file).
Upload your WAR file to Elastic Beanstalk using the AWS Management Console, the AWS Toolkit for Eclipse, the web service APIs, or the Command Line Tools.
Deploy your application. Behind the scenes, Elastic Beanstalk handles the provisioning of a load balancer and the deployment of your WAR file to one or more EC2 instances running the Apache Tomcat application server. Within a few minutes you will be able to access your application at a customized URL (e.g. http://myapp.elasticbeanstalk.com/).

Once an application is running, Elastic Beanstalk provides several management features such as:

Easily deploy new application versions to running environments (or rollback to a previous version).
Access built-in CloudWatch monitoring metrics such as average CPU utilization, request count, and average latency.
Receive e-mail notifications through Amazon Simple Notification Service when application health changes or application servers are added or removed.
Access Tomcat server log files without needing to login to the application servers.
Quickly restart the application servers on all EC2 instances with a single command.

Let's get the TravelLog started!

Eclipse Setup

Launch Eclipse.

Ideally, when you installed Eclipse for your last project, you chose to install "Eclipse IDE for Java EE Developers". That has all the necessary Eclipse packages. No? Not sure?

Install Eclipse support packages. Choose Help->Install New Software. Choose Work with: Indigio (http://download.eclipse.org/releases/indigo) (assuming that you have the latest "Indigo" version of Eclipse installed). Now check the installation box next to the following packages:

Database Development -> Data Tools Platform Enablement Extender SDK
Database Development -> Data Tools Platform Extender SDK
Web Development -> Eclipse Java EE Developer Tools
Web Development -> Eclipse Java Web Developer Tools
Web Development -> Eclipse Web Developer Tools

Select next/finish and accept the licenses. Allow the installation to complete, and restart Eclipse.

Install AWS Toolkit for Eclipse. Choose Help->Install New Software. Click the "Add" button next to "Work with". Enter AWS for the name and http://aws.amazon.com/eclipse/ for the location, and click OK. Now check the installation box next to the following packages:

AWS Toolkit for Eclipse - use the upper-level checkbox to include all the tools in this category

Select next/finish and accept the licenses. Allow the installation to complete, and restart Eclipse.

Configure AWS Toolkit

Launch Eclipse. In Eclipse, find the Orange AWS logo button on the top toolbar. (If you're at the home/splash screen, you need to enter the Project Explorer view first to see it.) Select the drop-down arrow next to the button, and choose "Preferences". Enter the following information for the default account:

Account Name: <Check file in Sakai drop-box for your username>
Access Key ID: <Check file Sakai drop-box>
Secret Acces Key: <Check file in Sakai drop-box>
Click OK when finished

Create New AWS Elastic Beanstalk Environment

In Eclipse, find the Orange AWS logo button on the top toolbar. Select the drop-down arrow next to the button, and choose "New AWS Elastic Beanstalk Environment". Select the AWS option for Tomcat 6 (not 7).

Leave the server host name as "localhost" (this isn't relevant)
Leave the server name as "AWS Elastic Beanstalk for Tomcat 6 at localhost" (this isn't relevant)
Click Next
Select a region for your Elastic Beanstalk application. (Currently, US-East is the only available region!)
Select create a new application

An Application is a logical collection of AWS Elastic Beanstalk components, including environments and versions. In AWS Elastic Beanstalk an application is conceptually similar to a folder.
Name: Enter something like YOURNAME-TravelLog
Description: Enter something like YOURNAME Travel Log

Configure a new environment for your application

An Environment represents the AWS resources (load balancer, auto-scaling group, and EC2 instances) created specifically to run your application. Each environment can run a single version of your program at a time.
Environment Name: YOURNAME-TravelLogEnv-1
Environment Description: YOURNAME Travel Log Environment #1

Click Next
Check "Deploy with Keypair" (so that you can SSH to your server using this keypair later)

Scroll and select your username on the list (recall that you previously create a keypair in the first tutorial)
Click the "gearbox" icon, and then navigate and find the .pem keypair file you previously downloaded in the first tutorial.
When properly selected, the red X next to your keypair name should turn into a green checkbox

Check "Assign CNAME to new server", and enter a CNAME for your site: YOURNAME-travellog

This will translate into a URL of http://YOURNAME-travellog.elasticbeanstalk.com

Enter the Health check URL: /healthcheck.jsp (this file exists as part of the demo project, and returns HTTP 200 OK as long as the server is running)
Email address for notifications: <use your email address>
Click Finish

Create New AWS Java Web Project

In Eclipse, choose File->New Project...->AWS->AWS Java Web Project. Click Next.

Pick a project name such as "TravelLog"
Select the user account that you created previously (i.e. your AWS username)
Select the "Travel Log" sample web application. If you don't do this, you won't get all the demo source code and files!
Click Finish, and give Eclipse a few seconds to download and index all the files.

Code Changes to Application

This demo application was not designed for a classroom tutorial environment, where we have many users sharing a single master account. As such, it comes hardwired to use "domains" (think: database tables) in Amazon's SimpleDB system with fixed names like TravelLog-Comment, TravelLog-Entry, etc... These domains are visible to any student under the common master account. Thus, the first student to create the tutorial wins, but only until the 2nd student starts running the app, at which point everyone fails! To avoid this scenario, you need to change the SimpleDB code to reference a unique domain names for your demo.

Open the file Java Resources->src->com.amazon.aws.samplecode.travellog.dao->TravelLogDAOSimpleDBImpl.java

Original code (to search for):

static {
   properties.put("lobBucketName", S3StorageManager.getKey().toLowerCase() + "-travellog-lob" + StageUtils.getResourceSuffixForCurrentStage());
 }
private static EntityManagerFactoryImpl factory = new EntityManagerFactoryImpl("TravelLog" + StageUtils.getResourceSuffixForCurrentStage(), properties);

New code to prefix the domain with your name:

static {
   properties.put("lobBucketName", S3StorageManager.getKey().toLowerCase() + "-YOURNAME-travellog-lob" + StageUtils.getResourceSuffixForCurrentStage());
 }
 private static EntityManagerFactoryImpl factory = new EntityManagerFactoryImpl("YOURNAME-TravelLog" + StageUtils.getResourceSuffixForCurrentStage(), properties);

This code updates both SimpleDB domains to use names of the form "YOURNAME-TravelLog", and updates the "LOB" buckets in Amazon S3 (used for storing Travel Log images) to also contain YOURNAME as a prefix.

Run Application

This step does a lot!

Compiles your app in a Java Web Archive (.war) file
Uploads your app to S3 (in a new bucket with the name elastic_beanstalk_xxxxxx)
Launches 1+ EC2 instances to be part of your new environment
Runs a Java server associated environment (Apache Tomcat / Apache Maven) in that EC2 instance
Runs your program

Time to run your app! Right click on project name -> Run As -> Run On Server.

Select "Choose an existing server".
Choose your Elastic Beanstalk config just created. The environment name you selected should appear here.
Click Finish
Enter a version label to identify this specific .war program from any other .war files you might later upload as part of this same program: v1
Wait. Give Eclipse a few minutes to upload the file and for Amazon to launch an EC2 instance.
While waiting, you can check your email, and follow the link to enable notifications from Amazon for this specific environment.

When finished, Elipse should show a preview window of your web app. The first page will prompt you (the administrator) to set a password to control the blog.

Your app has at least three different URLs to allow access:

ElasticBeanstalk URL:

Example: http://shafer-travellogenv-1-rgeqedcphq.elasticbeanstalk.com
Find this URL in Eclipse from the preview window

Specific server URL:

Example: http://ec2-174-129-186-72.compute-1.amazonaws.com
Find this URL by logging into the Amazon web control panel, selecting the EC2 tab, finding your running instance (look at the keypair column to distinguish your servers from your classmates), click on it, and note the "Public DNS" name shown
This URL will only go to one specific server, regardless of how many servers you have in your environment.

Load balancer URL:

Example: http://awseb-shafer-travellogenv-1-1125419408.us-east-1.elb.amazonaws.com
Find this URL by logging into the Amazon web control panel, selecting the EC2 tab, selecting the Load Balancer option, finding your running load balancer (which should contain your environment name), click on it, and note first DNS name shown.

This load balancer URL will spread out requests across all your servers (although we only have 1 at the moment)

Tutorial Checkpoint: Open three tables in your web browser, and show me your application accessed through the three different DNS entries (beanstalk URL, specific server URL, and load balancer URL).

Forget how to access the Amazon web control panel? You need to use the "secret" address as part of your IAM account - check the Sakai dropbox for details.

Code Development

At this point, you could make modifications to the web application, and repeat the run-as progress to get Eclipse to upload a new version of your application to the server and execute it - no restarting required!

Cleanup

There is a lot to cleanup after this demo runs:

Shut down the EC2 instance(s) used in your environment:

Log onto the Amazon web control panel
Choose Elastic Beanstalk tab
Find your application in the dropdown box (See why we tagged it with your name?)
Select Actions->"Terminate this Environment" to stop your running instance(s) of your app

You could also accomplish this same tasks from Eclipse! Click the Amazon logo and choose "Open AWS Management Perspective", and then browse the entries under "AWS Explorer". There is a LOT here!

Delete the Elastic Beanstalk Application and saved versions:

Log onto the Amazon web control planel

Choose Elastic Beanstalk tab
Find your application in the dropdown box
Select Versions tab
Check all checkboxes next to the version(s) listed, click "Delete Versions"
Choose "Delete version from Amazon S3 as well" and click "Yes, Delete"
Go back to the Overview sub-tab, and choose "Delete Application"

Delete the SimpleDB database:

In Eclipse, choose "Open AWS Management Perspective".
Expand the Amazon SimpleDB category
Right-click and choose "Delete Domain" for all of the TravelLog entries. (You can shift-click to select a group at once)

Question during the tutorial: Will we see databases for all the other accounts? Or is this private by username?
Tip: If you screw up your Travel Log badly, you can always just delete all these domains and then use the AWS web control panel / Elastic Beanstalk tab to "Restart the App Server(s)" to reset

Delete the S3 buckets used to store image:

The application creates buckets in S3 with names like <randomstring>-travellog. I don't think you can tell them apart from other students in the class, however.... (Due to the shared overall account...)

References

This tutorial has been adapted from material at: