Carafe

This is a tool for deploying Elixir applications, built upon capistrano.

Carafe requires git for hosting the source repository. It depends on Edeliver for a few parts that are not handled in Carafe yet. Release building requires Distillery.

Currently, only full releases, not upgrades, are supported, and archives are kept locally.

Installation

Prerequisites, Ruby side

You need ruby >= 2.0 installed in your development environment. The recommended way of installing dependencies on the ruby side is via bundler. Create a Gemfile at the project root containing:

source "https://rubygems.org"

group :development do
  gem "carafe"
end

Then run bundle install --path vendor/bundle, followed by bundle exec cap install. This gives you these additional files:

o .bundle/config
+ Capfile
+ Gemfile
+ Gemfile.lock
o vendor/bundle
+ config/deploy.rb
+ config/deploy/staging.rb
+ config/deploy/production.rb

Files behind o should be gitignored, the others checked in. Add the following line to the Capfile:

require "carafe"

Prerequisites, Elixir side

Add these deps to your mix.exs:

  defp deps do
    [
      {:edeliver, "~> 1.4.2"},
      {:distillery, "~> 0.9"},
      {:carafe, "0.2.0"}
    ]
  end

and run mix deps.get. Add :edeliver to your :extra_applications AS LAST:

  def application do
    [extra_applications: [:logger, :edeliver]]
  end

Configuration

First, configure your application for distillery.

The Capistrano documentation on configuration gives you all the technical details on configuration in general. Note that Carafe does not use most of the variables listed there. Below you find a short introduction that gets you started.

General configuration goes into config/deploy.rb. Capistrano has the concept of "stages", and stage specific configuration goes into separate files. For the production stage this would be config/deploy/production.rb. Stage specific configuration has precedence over general one.

To configure the deployment process, we mostly set variables and declare servers, as in this example snippet:

set :application, "my_app"
set :repo_url, "https://github.com/...."

set :repo_path, "dummy1_repo"
set :build_path, "build_path"
server "buildhost1", user: "user", roles: ["build"]

Note we are declaring a host (and how to connect to via ssh) to be a build host by giving it the "build" role. There obviously must be only one buildhost. In config/deploy/production.rb, we might write

server "main", user: "user", roles: ["app"]

to declare a server as a node to deploy our app to. Documentation on the server options can be found here.

Here are the config variables honored by carafe:

Varible	Used for/as...
:branch	git branch to build the release from, or :current for current branch
:repo_url	cloning the repo on the build host
:repo_path	path of repository cache on build host
:mix_env	MIX_ENV environment when running release mix task from distillery
:application	name of the OTP application
:distillery_environment	name of the distillery environment, defaulting to the value of :mix_env
:build_path	path to build release on build host
:app_path	path on application server where releases are unpacked and operated

Umbrella project deployments

A demonstration for an umbrella project is in the dummies/dummy2 test dummy project.

Usage

Currently, only deploying releases is supported. Every deploy scenario is a bit different, so you need to tell how a deploy is to be done. In deploy.rb, add the following line:

task "deploy" => [
  "buildhost:generate_release",
  "buildhost:archive:download",
  "node:archive:upload_and_unpack",
  "node:full_restart"
]

You should now be able to perform a production deploy with the command bundle exec cap production deploy.

Development & Contributing

Coming soon.