Archive for February, 2011

How to customize an Amazon Elastic Beanstalk instance

February 8th, 2011 9 comments

The default Amazon Elastic Beanstalk AMI provides a Java-based application container with Apache Tomcat as the work horse. All you have to do is to deploy a standard Java WAR file containing your web application.

But sometimes, the standard AMI does not provide everything. Maybe the Apache configuration needs to be tweaked or some package, e.g. a local memcached server, is missing.

Customizing the Beanstalk AMI is easy, there are only a few simple steps, which are outlined here.

First of all, start the AMI to be customized in the AWS console. Note: as described by foremosttravel in the Beanstalk forum, the instance should be started from the EC2 console, NOT the Beanstalk console, as running the AMI within the Beanstalk environment may lead to it being terminated during the EBS snapshot, as it might fail to answer to the Beanstalk health checks.


So here are the step by step instructions for the preparation:

  1. Go to the EC2 console
  2. Select region US-East, as Beanstalk is currently available only there
  3. Click Launch instance
  4. Enter either ami-100fff79 for the 64bit AMI or ami-060fff6f for the 32bit AMI (as of Feb 8th, 2011; these AMIs contain fixes to preserve the original hostname and protocol, which are stripped by the load balancer)

    Start instance from EC2 console

  5. Click Select, then Continue, until the step Create Key Pair
  6. Choose an existing key pair or create a new one. This will be used to access the running instance using SSH
  7. In the next step, specify an appropriate security group, which allows SSH access, e.g. SSH
  8. Press continue and finally launch the instance
  9. In the instance list, press the right mouse button over the instance and choose Connect
  10. Copy the SSH command line, adjust the path to your private key and connect to the instance using a SSH client.

    Note: you need to connect as user ec2-user, root access can be obtained using the command sudo su -. See this blog post for details on how to access the instance.


Now we are free to customize the AMI’s files to our heart’s content.

Note: As the AMI is running outside the Beanstalk environment, Apache, Tomcat, and HostManager (the software interface to Beanstalk), are not running, as they didn’t get the expected parameters, such as the path of the application to start. This doesn’t matter, as soon as we start the customized AMI in an Beanstalk environment, everything works again.

As a proof of concept, we change HostManager‘s default index page (/opt/elasticbeanstalk/srv/hostmanager/views/index.erb) to contain the following HTML body:

<body style="font-family:Verdana,Arial,Sans-serif;">
<div class="logo">
<img src="" />
<h2>Host Manager</h2>
<b>Haz customization!</b>

Note: when changing HostManager or the Apache configuration, please make sure, that HostManager still answers to Beanstalk requests on /_hostmanager and the application to health checks on /, otherwise the instance will be terminated and another will be started!

Persisting changes

Now that we are done, we need to create an EBS snapshot to preserve our customizations. The AMI is EBS-backed, so a snapshot can be used to register an AMI, which is based on the snapshot.

Again, here are the step by step instructions:

  1. Remove eveything you do not want to remain in the instance such as the bash history, SSH keys, …
  2. Create an EBS snapshot, either from the EC2 console or the command line tools. See the user guide for details.
  3. You now have an AMI. See Images > AMI on the left side of the EC2 console and choose Owned By Me in the AMI tab to view your newly create AMI. Note down the AMI id.

If you want to make some more changes, keep the current instance running, while you test your changes from within Beanstalk. After a test drive (see below), make some more changes and create another image. Rinse and repeat until you are satisfied with the results. Don’t forget to clean up any unnecessary EBS snapshots and AMIs, as they cost actual money!

Start customized instance in Beanstalk

If you want to test-drive your customized AMI, you need to start an Beanstalk environment with the id of the customized AMI. There are two ways to perform this, via the Beanstalk console or from the command line.

Via Beanstalk console

  1. Go to the Beanstalk console
  2. Create an environment
  3. Wait for everything to be started so you can change the configuration
  4. Adjust the AMI id as described in the user guide
  5. Restart the environment
  6. Test your changes. In our example, we go to the changed HostManager index page at

Via command line

We use my simplified script to start an Amazon Elastic Beanstalk application from command line. See here for a detailed description. We can specify all parameters right from the start, so we do not need to wait for the initial start, before we can adjust the configuration.

  1. Download the script from GitHub
  2. Start an environment with the following command: -a myapp -i ami-be55a5d7 -t t1.micro -C 64 -e myenv -k mykeypair

    Make sure to specify the id of your AMI as created above. Also don’t forget to specify a keypair, otherwise you won’t be able to log in using SSH. The name of the environment must be unique, as it is also used as CNAME (this can be overridden with -c <CNAME> though)

  3. Test your changes. In our example, we go to the changed HostManager index page at


Have fun creating customized instances. Please leave feedback and/or a note in the comments, which describes your changes. I will try to change HostManager to run the Virgo OSGi server instead of Tomcat, so stay tuned for the next installment.

Categories: amazon, beanstalk, ec2 Tags:

Script to start an Amazon Elastic Beanstalk application from command line

February 3rd, 2011 Comments off

After playing around with Amazon Elastic Beanstalk, I started to explore the command line tools.

Starting an Amazon Elastic Beanstalk application from the AWS console is easy and reasonably fast. The main problem is that you can’t currently provide additional settings such as the instance type (e.g. m1.small or t1.micro), a SSH key or application parameters.

After starting the application environment, it must be stopped again, before the configuration can be changed. This costs an instance hour but, more importantly, this procedure takes quite a while, as AWS must reconfigure the load balancer, auto-scaling group, start your instance(s), etc.

I created a script, which can be used to start an application environment from the command line. The most important parameters can be set as command line parameters:

All you need is to install the Elastic Beanstalk command line tools and my script.


Starting an application myapp with environment myenv on a m1.small instance with SSH key mysshkey is as simple as: -a myapp -k mysshkey -e myenv -t m1.small -f 'mybucket/myapp.war'

Some notes:

  • the application WAR file must already be uploaded to S3. The format of the file name (parameter -f) is bucketname/key. If the file name is not specified, Beanstalk will deploy the sample application
  • the environment can only be created, if the CNAME (which is identical to the environment name, if not specified with -c) is not already used. The CNAME is used as sub-domain under When creating an environment with name (and CNAME) myenv, the full DNS name would be
  • starting an environment will fail, if the SSH key name does not exist. You can look up the name of your SSH key in the EC2 console

Elastic Beanstalk Parameters

Elastic Beanstalk provides many parameters, which can be set. A full list can be obtained using elastic-beanstalk-describe-configuration-settings, also from the command line tools (NOTE: fix required!).

I created a list of all Elastic Beanstalk configuration options using another script (requires ruby gem jazor):

The long version in JSON format is available here.

Final words

Starting an application environment is easy and the command line tools help a lot. There are still some bugs, but I’m sure, the Beanstalk team will address them soon. The forum is a great resource.

My next post will be about creating a customized Beanstalk AMI. Stay tuned!

Categories: amazon, beanstalk, ec2 Tags:
Fork me on GitHub