lein-beanstalk
Leiningen plugin for Amazon's Elastic Beanstalk.
Prerequisites
You will need an Amazon Web Services account, and know your account key and secret key.
You will also need to be signed up for Elastic Beanstalk.
Basic Configuration
To use lein-beanstalk, you'll need to add a few additional values to
your project.clj
file.
First, add lein-beanstalk as a plugin:
:plugins [[lein-beanstalk "0.2.2"]]
or, if you're using a version of Leiningen prior to 1.7.0, add it to
your :dev-dependencies
:
:dev-dependencies [[lein-beanstalk "0.2.2"]]
Then add a lein-beanstalk-credentials
definition to your
~/.lein/init.clj
file that contains your AWS credentials:
(def lein-beanstalk-credentials
{:access-key "XXXXXXXXXXXXXXXXXX"
:secret-key "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"})
Deploy
You should now be able to deploy your application to the Amazon cloud using the following command:
$ lein beanstalk deploy development
Info
To get information about the application itself run
$ lein beanstalk info
Application Name : myapp
Description : My Awesome Compojure App
Last 5 Versions : 0.1.0-20110209030504
0.1.0-20110209030031
0.1.0-20110209025533
0.1.0-20110209021110
0.1.0-20110209015216
Created On : Wed Feb 09 03:00:45 EST 2011
Updated On : Wed Feb 09 03:00:45 EST 2011
Deployed Envs : development (Ready)
staging (Ready)
production (Terminated)
and information about a particular environment execute
$ lein beanstalk info development
Environment Id : e-lm32mpkr6t
Application Name : myapp
Environment Name : development
Description : Default environment for the myapp application.
URL : development-feihvibqb.elasticbeanstalk.com
LoadBalancer URL : awseb-myapp-46156215.us-east-1.elb.amazonaws.com
Status : Ready
Health : Green
Current Version : 0.1.0-20110209030504
Solution Stack : 32bit Amazon Linux running Tomcat 6
Created On : Tue Feb 08 08:01:44 EST 2011
Updated On : Tue Feb 08 08:05:01 EST 2011
Shutdown
To shutdown an existing environment use the following command
$ lein beanstalk terminate development
This terminates the environment and all of its resources, i.e. the Auto Scaling group, LoadBalancer, etc.
Cleanup
To remove any unused versions from the S3 bucket run
$ lein beanstalk clean
Configuration
AWS Credentials
The Amazon Web Services account key and secret key should be
put into a lein-beanstalk-credentials
definition in your
~/.lein/init.clj
file:
(def lein-beanstalk-credentials
{:access-key "XXXXXXXXXXXXXXXXXX"
:secret-key "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"})
Keeping your credentials out of your project.clj
file and out
of your project in general helps ensure you don't accidentally
commit your credentials to github et al.
Environments
Elastic Beanstalk environments can be defined in multiple ways in
the project.clj
file.
If no environments are specified, lein-beanstalk will create three default environments
development
(with CNAME prefixmyapp-development
)staging
(with CNAME prefixmyapp-staging
)production
(with CNAME prefixmyapp
)
To override the default behavior, add an :aws
key to your
project.clj
file, either with :environments
mapped to a
vector of envionment symbols:
:aws {:beanstalk {:environments [dev demo prod]
...}
...}
or to a vector of maps
:aws {:beanstalk {:environments [{:name "dev"}
{:name "demo"}
{:name "prod"}]
...}
...}
Given either of the above configurations, the following two environents will be created:
dev
(with CNAME prefixmyapp-dev
)demo
(with CNAME prefixmyapp-demo
)prod
(with CNAME prefixmyapp-prod
)
The second option allows one to specify the CNAME prefix for each environment
:aws {:beanstalk {:environments [{:name "dev"
:canme-prefix "myapp-development"}
{:name "staging"
:cname-prefix "myapp-demo"}
{:name "prod"
:canme-prefix "myapp"}]
...}
...}
By default the CNAME prefix is <project-name>-<environment>
.
S3 Buckets
Amazon Elastic Beanstalk uses
Amazon Simple Storage Service (S3) to store the versions
of the application. By default lein-beanstalk uses
lein-beanstalk.<project-name>
as the S3 bucket name.
To use a custom bucket, specify it in the project.clj
file:
:aws {:beanstalk {:s3-bucket "my-private-bucket"
...}}
Trouble-Shooting
Q: Why does my deployed web application still shows up as 'red' in the Elastic Beanstalk console?
A: Elastic Beanstalk sends a HTTP HEAD
request to '/' to check if
the application is running. Simply add the necessary handling to the
application. e.g. for Compojure add
(HEAD "/" [] "")