A provider is an interface to taking code on GitHub at a specific sha and doing something with it. Heaven comes with two example providers that show off how to interact with HTTP APIs(heroku) as well as shelling out(capistrano). It should be easy to adapt to things like fabric, chef, and puppet as well.
All providers run inside of resque jobs and have a configurable timeout.
module Provider
class Fabric < DefaultProvider
def execute
end
def notify
end
end
endJobs will timeout if they don't complete in 300 seconds. If you really need more than that you can configure the timeout by setting the DEPLOYMENT_TIMEOUT environmental variable to the number of seconds you'd like to increase it to.
Heaven runs most of the deployment tasks in a child process, that by default does not die when the deployment timeouts. To enable terminating the deployment child processes, set TERMINATE_CHILD_PROCESS_ON_TIMEOUT to 1.
The heroku provider uses the build and release API. It requests an archive link from GitHub and passes that on to heroku. It polls the API every few seconds until the heroku build api completes.
| Environmental Variables | |
|---|---|
| HEROKU_API_KEY | A direct authorization token from heroku |
+--------+ +----------+ +-------------+
| GitHub | | Heaven | | Heroku |
+--------+ +----------+ +-------------+
| | |
| Deployment Event | |
|---------------------->| |
| | |
| | |
| Request Download URL | |
|<----------------------| |
| | |
| | |
| Expiring Tarball URL | |
|---------------------->| |
| | |
| | |
| | Create Build |
| |-------------------->|
| | |
| | |
| Deployment Status | |
|<----------------------| |
| | |
| | |
| | Request Status |
| |-------------------->|
| | |
| | |
| | Loops until done |
| |<--------------------|
| | |
| | |
| Deployment Status | |
|<----------------------| |
| | |
Capistrano gives you a distributed task management system over ssh. The heaven provider gives you support for three options in capistrano.
- environment
- branch
- task
| Environmental Variables | |
|---|---|
| DEPLOYMENT_PRIVATE_KEY | An ssh private key used to login to your remote servers via SSH. Put it all on one line with \n in it. |
You need to configure your :repository option in your Capfile to use an https remote. The git interactions will always be over https and the ssh interactions will only involve accessing your servers.
Below is a simple capfile that works with passenger.
require "bundler/capistrano"
default_run_options[:pty] = true
set :ruby_path, "/usr/local/rbenv/versions/1.9.3-p448/bin/"
set :application, "heaven"
set :default_environment, {
'PATH' => "#{ruby_path}:$PATH",
'RAILS_ENV' => 'production'
}
set :scm, :git
set :branch, (ENV['CAP_BRANCH'] || 'master')
set :deploy_via, :remote_cache
set :repository, "https://github.com/atmos/heaven"
set :user, "atmos"
set :use_sudo, false
set :ssh_options, {:forward_agent => true}
set :deploy_to, "/app/#{application}"
set :target_server, "mybox.mydomain.com"
role :app, target_server
role :web, target_server
role :db, target_server, :primary => true
task :production do
end
namespace :deploy do
desc "Run migrations"
task :migrate, :roles => :db do
run "cd #{current_path} && bin/rake db:migrate"
end
desc "Restart Application"
task :restart, :roles => :app do
run "touch #{current_path}/tmp/restart.txt"
end
end+--------+ +----------+ +-------------+
| GitHub | | Heaven | | SSH Host |
+--------+ +----------+ +-------------+
| | |
| Deployment Event | |
|---------------------->| |
| | |
| | |
| Fetch ref/sha | |
|<----------------------| |
| | |
| | |
| Return latest ref | |
|---------------------->| |
| | |
| | |
| | SSH into host |
| |-------------------->|
| | |
| | |
| Deployment Status | |
|<----------------------| |
| | |
| | |
| | bundles/restarts |
| |<--------------------|
| | |
| | |
| Deployment Status | |
|<----------------------| |
| | |
Bundler enabled Capistrano deployment lets you deploy using Capistrano in a fresh bundler environment. The provider will install the gems from your project's :deployment and :heaven groups and use that environment to run Capistrano. The same configuration applies for Bundler Capistrano than for Capistrano provider. One caveat:
The provider passes the ref being deployed to capistrano in an environment variable BRANCH. In your Capfile, you'll need to add:
set :branch, (ENV['BRANCH'] || fetch(:branch, 'master'))| Environmental Variables | |
|---|---|
| BUNDLER_PRIVATE_SOURCE | Private gem source. Optional. |
| BUNDLER_PRIVATE_CREDENTIALS | Private gem source credentials. Can be a token or a username:password combination. Optional. |
Fabric enables distributed task management system over ssh. The heaven provider gives you support for three options.
- environment
- branch
- task
| Environmental Variables | |
|---|---|
| DEPLOYMENT_PRIVATE_KEY | An ssh private key used to login to your remote servers via SSH. Put it all on one line with \n in it. |
| Environmental Variables | |
|---|---|
| DEPLOY_COMMAND_FORMAT | Allows you to define the specific task calling format for your fabric file. Defaults to: fab -R %{environment} %{task}:branch_name=%{ref} |
With Elastic beanstalk you can quickly deploy and manage applications in the AWS cloud without worrying about the infrastructure that runs those applications.
- environment
- branch
| Environmental Variables | |
|---|---|
| BEANSTALK_S3_BUCKET | The bucket to store s3 archives in. |
| BEANSTALK_ACCESS_KEY_ID | The AWS access key id for API interaction with Amazon. |
| BEANSTALK_SECRET_ACCESS_KEY | The AWS secret access key for API interaction with Amazon. |
| Environmental Variables | |
|---|---|
Shell provider lets you run an arbitrary script from the repo to perform the deployment. The script receives BRANCH, SHA, DEPLOY_TASK and DEPLOY_ENV environment variables when executing. This is ideal provider if your deployment consists only of for example asset compilation and upload to S3.
No configuration required in heaven. You must add "deploy_script" key to your apps.json configuration that must point to an executable file inside the repository.