Home > amazon, beanstalk, ec2 > How to customize an Amazon Elastic Beanstalk instance

How to customize an Amazon Elastic Beanstalk instance

February 8th, 2011

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="http://awsmedia.s3.amazonaws.com/logo_aws.gif" />
<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 http://myenv.elasticbeanstalk.com/_hostmanager

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:
    eb-create-app.sh -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 http://myenv.elasticbeanstalk.com/_hostmanager


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:
  1. Lucas Teixeira
    February 10th, 2011 at 01:32 | #1

    Excellent writing!

    I didn’t know was so easy as this!
    This can solve many other problems like installing memcached, terracotta and other stuff!

    Thanks Wolfgang!

  2. Greg
    April 19th, 2011 at 04:19 | #2

    Thanks Wolfgang! Your tutorials have been great!

  3. Boomie
    May 21st, 2011 at 21:45 | #3

    Your tutorials *have* been awesome. 🙂 I’ve been reading them, and am now a fan.

    I did have one question I thought you might be able to answer quickly: Should I be able to change the time zone of the instance using an AMI file?

  4. May 23rd, 2011 at 21:37 | #4

    Thanks 🙂

    In your customized AMI you can change the timezone using standard Linux configuration tools. If you need a different timezone for your Java app only, you could simply add a ServletContextListener, which sets the timezone using TimeZone#setDefault().

  5. October 27th, 2011 at 03:46 | #5

    I have wasted hours trying to customize an AMI started from Beanstalk console, before I found your article.

    Thanks for sharing!

  6. Danilo
    April 1st, 2012 at 01:30 | #6

    Is it possible to actually use the Beanstalk AMI without Beanstalk, I mean, launching through EC2 manually, start the services, interact with HostManager, etc?

    I’m trying, but It’s not working. The _hostmanager url return 503. httpd and hostmanager seems to be running.


  7. April 1st, 2012 at 09:51 | #7

    You can Launch and use this AMI, but in order to use hostmanager, you would need to provide it with some input it expects, such as where to download the WAR from (including signed S3 link), etc.

    I haven’t looked into the startup for a while, so, sorry, I can’t help you here…

  8. me
    April 13th, 2012 at 07:49 | #8

    How does uploading a new version work in a customized ami scenario?

  9. April 13th, 2012 at 12:54 | #9

    No difference to stock AMI: hostmanager, which must also be present on the custmized AMI, handles everything. The startup data contains all information on where to download the WAR file from and which parameters to apply.

Comments are closed.
Fork me on GitHub