# 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 ""

group :development do
  gem "carafe"

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"}

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

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

## 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, ""

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" => [

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

## Development & Contributing

Coming soon.