README.md in engineyard-hudson-0.2.0 vs README.md in engineyard-hudson-0.2.1

- old
+ new

@@ -2,11 +2,11 @@ Run your continuous integration (CI) tests against your Engine Yard AppCloud environments - the exact same configuration you are using in production! You're developing on OS X or Windows, deploying to Engine Yard AppCloud (Gentoo/Linux), and you're running your CI on your local machine or a spare Ubuntu machine in the corner of the office, or ... you're not running CI at all? -It's a nightmare. It was for me. [Hudson CI](http://hudson-ci.org/), `engineyard-hudson` and the [hudson](http://github.com/cowboyd/hudson.rb) CLI projects now make CI easier to do than not to. A few commands and your Rails applications' tests are automatically running, no additional setup, and its the same environment you are deploying your Rails applications (Engine Yard AppCloud). Sweet. +It's a nightmare. It was for me. [Hudson CI](http://hudson-ci.org/), the [hudson](http://github.com/cowboyd/hudson.rb) CLI project, and **engineyard-hudson** now make CI easier to do than not to. A few quick commands and your Rails applications' tests are automatically running, no additional setup, and its the same environment you are deploying your Rails applications (Engine Yard AppCloud). Sweet. ## Installation gem install engineyard-hudson @@ -22,13 +22,12 @@ ## Warning (aka TODO list) In the very first release of `engineyard-hudson`: -* there is no support for authentication/authorization of Hudson CI. -* git URLs are converted to public `git://` urls on Hudson; until deploy key support is added -* no mail server configured for Hudson CI build failure notifications +* There is no support for authentication/authorization of Hudson CI. It _will_ use the deploy keys already installed on your AppCloud instance, as described in engineyard-serverside [#set_up_git_ssh](http://github.com/engineyard/engineyard-serverside/blob/master/lib/engineyard-serverside/strategies/git.rb#L106-134) +* No mail server configured for Hudson CI build failure notifications. That is, its really only useful - at this very "alpha" instant in time - to Open Source Rails projects. But that's just me being brutally honest. ## Hosting Hudson CI @@ -48,20 +47,24 @@ * run: ey recipes apply # to select environment * Boot your environment if not already booted. Do those steps and you're done! Now, you either visit your Hudson CI site or use `hudson list` to see the status of your projects being tested. +Note: the Hudson CI environment in Engine Yard AppCloud must be a single instance "solo". + ### Hosting elsewhere You need the following information about your Hudson CI: * Hudson CI public host (& port) * Hudson CI's user's public key (probably at /home/hudson/.ssh/id_rsa.pub) * Hudson CI's user's private key path (probably /home/hudson/.ssh/id_rsa) ## Running your tests in Hudson against Engine Yard AppCloud +This is the exciting part - ensuring that your CI tests are being run in the same environment as your production applications. In this case, on Engine Yard AppCloud. + Just a few steps and you will have your applications' tests running. $ cd /my/project $ ey-hudson install . @@ -71,10 +74,58 @@ * run: ey recipes apply # to select environment * Boot your environment if not already booted. Do those steps and you're done! Now, you either visit your Hudson CI site or use `hudson list` to see the status of your projects being tested. +### Conventions/Requirements + +* Do not use your production environment as your Hudson CI slave. There are no guarantees what will happen. I expect bad things. +* You must name your CI environment with a suffix of `_ci` or `_hudson_slave`. +* You should not name any other environments with a suffix of `_ci` or `_hudson_slave`; lest they offer themselves to your Hudson CI as slave nodes. +* Keep your production and CI environments exactly the same. Use the same Ruby implementation/version, same database, and include the same RubyGems and Unix packages. Why? This is the entire point of the exercise: to run your CI tests in the same environment as your production application runs. + +For example, note the naming convention of the two CI environments below (one ends in `_hudson_slave` and the other `_ci`). + +<img src="http://img.skitch.com/20101031-dxnk7hbn32yce9rum1ctwjwt1w.png" style="width: 100%"> + +### What happens? + +When you boot your Engine Yard AppCloud CI environments, each resulting EC2 instance executes a special "hudson_slave" recipe (see `cookbooks/hudson_slave/recipes/default.rb` in your project). This does three things: + +* Adds this instance to your Hudson CI server as a slave +* Adds each Rails/Rack application for the AppCloud environment into your Hudson CI as a "job". +* Commences the first build of any newly added job. + +If your CI instances have already been booted and you re-apply the recipes over and over (`ey recipes apply`), nothing good or bad will happen. The instances will stay registered as slaves and the applications will stay registered as Hudson CI jobs. + +If a new application is on the instance, then a new job will be created on Hudson CI. + +To delete a job from Hudson CI, you should also delete it from your AppCloud CI environment to ensure it isn't re-added the next time you re-apply or re-build or terminate/boot your CI environment. (To delete a job, use the Hudson CI UI or `hudson remove APP-NAME` from the CLI.) + +In essence, to add new Rails/Rack applications into your Hudson CI server you: + +* Add them to one of your Engine Yard AppCloud CI environments (the one that matches the production environment where the application will be hosted) +* Rebuild the environment or re-apply the custom recipes (`ey recipes apply`) + +### Applications are run in their respective CI environment + +Thusly demonstrated below: the application/job "ci_demo_app" is in the middle of a build on its target slave "ci_demo_app_ci". See the AppCloud UI example above to see the relationship between the application/job names and the environment/slave names. + +<img src="http://img.skitch.com/20101031-tga2f23wems1acpad1ua41qdmb.png" style="width: 100%"> + +### Can I add applications/jobs to Hudson CI other ways? + +Yes. There are three simple ways to get Hudson CI to run tests for your application ("create a job to run builds"). Above is the first: all "applications" on the Engine Yard AppCloud CI environment will automatically become Hudson CI jobs. The alternates are: + +* Use the `hudson create .` command from the [hudson](http://github.com/cowboyd/hudson.rb) CLI. + +Pass the `--assigned_node xyz` flag to make the project's test be executed on a specific slave node. "xyz" is the name of another application on your AppCloud account; your tests will be executed on the same instance, with the same version of Ruby etc. + +* Use the Hudson CI UI to create a new job. As above, you can make sure the tests are run on a specific Engine Yard AppCloud instance by setting the assigned node label to be the same as another AppCloud application in your account that is being tested. + +Specifically, Hudson CI uses "labels" to match jobs to slaves. A common example usage is to label a Windows slave as "windows". A job could then be restricted to only running on slaves with label "windows". We are using this same mechanism. + ## Automatically triggering job builds In Hudson CI, a "job" is one of your projects. Each time it runs your tests, it is called a "build". It is often desirable to have your SCM trigger Hudson CI to run your job build whenever you push new code. @@ -95,21 +146,21 @@ ### CLI Using the `hudson` CLI: - hudson build APP-NAME + hudson build path/to/APP-NAME ### Curl You are triggering the build via a GET call to an URL endpoint. So you can also use `curl`: curl http://HUDSON-CI-URL/job/APP-NAME/build ## Contributions -* Dr Nic Williams -* Bo Jeanes - initial chef recipes for Hudson server + slave +* Dr Nic Williams ([drnic](http://github.com/drnic)) +* Bodaniel Jeanes ([bjeanes](http://github.com/bjeanes)) - initial chef recipes for [Hudson server + slave](http://github.com/bjeanes/ey-cloud-recipes) ## License Copyright (c) 2010 Dr Nic Williams, Engine Yard \ No newline at end of file