Merge branch 'release/0.4.0' into stable

Author: holetse

README.md

@@ -15,14 +15,14 @@ add additional support.
 ```elixir
 def deps do
   [{:distillery, "~> 1.3",
-   {:bootleg, "~> 0.3"}]
+   {:bootleg, "~> 0.4"}]
 end
 ```
 
 ## Build server setup
 
 In order to build your project, Bootleg requires that your build server be set up to compile
-Elixir code. Make sure you have already installed Elixir on any build server you define. The remote
+Elixir code. Make sure you have already installed Elixir on any build server you define.
 
 
 ## Quick Start
@@ -42,8 +42,8 @@ $ mix bootleg.init
 # config/deploy.exs
 use Bootleg.Config
 
-role :build, "your-build-server.local", user: "develop", password: "bu1ldm3", workspace "/some/build/workspace"
-role :app, ["web1", "web2", "web3"], user: "admin", password: "d3pl0y", workspace "/var/myapp"
+role :build, "your-build-server.local", user: "develop", password: "bu1ldm3", workspace: "/some/build/workspace"
+role :app, ["web1", "web2", "web3"], user: "admin", password: "d3pl0y", workspace: "/var/myapp"
 ```
 
 ### build and deploy
@@ -68,6 +68,52 @@ role :build, "build.example.com", user, "build", port: "2222", workspace: "/tmp/
 role :app, ["web1.example.com", "web2.myapp.com"], user: "admin", workspace: "/var/www/myapp"
 ```
 
+### Environments
+
+Bootleg has its own concept of environments, which is analogous to but different from `MIX_ENV`. Bootleg environments
+are used if you have multiple clusters that you deploy your code to, such as a QA or staging cluster, in addition to
+your `production` cluster. Your main Bootleg config still goes in `config/deploy.exs`, and environment specific details
+goes in `config/deploy/your_bootleg_env.exs`. The selected environment config file gets loaded immediately after
+`config/deploy.exs`. To invoke a Bootleg command with a specific environment, simply pass it as the first argument to
+any bootleg Mix command.
+
+For example, say you have both a `production` and a `staging` cluster. Your configuration might look like:
+
+```elixir
+# config/deploy.exs
+use Bootleg.Config
+
+task :my_nifty_thing do
+  Some.jazz()
+end
+
+after_task :deploy, :my_nifty_thing
+
+role :build, "build.example.com", user, "build", port: "2222", workspace: "/tmp/build/myapp"
+```
+
+```elixir
+# config/deploy/production.exs
+use Bootleg.Config
+
+role :app, ["web1.example.com", "web2.example.com"], user: "admin", workspace: "/var/www/myapp"
+```
+
+```elixir
+# config/deploy/staging.exs
+use Bootleg.Config
+
+role :app, ["stage1.example.com", "stage2.example.com"], user: "admin", workspace: "/var/www/myapp"
+```
+
+
+Then if you wanted to update staging, you would `mix bootleg.update staging`. If you wanted to update production,
+it would be `mix bootleg.update production`, or just `mix bootleg.update` (the default environment is `production`).
+
+It is not a requirement that you define an environment file for each environment, but you will get a warning if
+a specific environment file can't be found. It is strongly encouraged to have an environment file per environment.
+
+
 ## Roles
 
 Actions in Bootleg are paired with roles, which are simply a collection of hosts that are responsible for the same function, for example building a release, archiving a release, or executing commands against a running application.
@@ -135,7 +181,7 @@ Bootleg extensions may impose restrictions on certain roles, such as restricting
 
 * `build` - Takes only one host. If a list is given, only the first hosts is
 used and a warning may result. If this role isn't set the release packaging will be done locally.
-* `app` -  Takes a lists of hosts, or a string with one host.
+* `app` -  Takes a list of hosts, or a string with one host.
 
 ## Building and deploying a release
 
@@ -154,6 +200,14 @@ mix bootleg.update production
 Note that `bootleg.update` will stop any running nodes and then perform a cold start. The stop is performed with
 the task `stop_silent`, which differs from `stop` in that it does not fail if the node is already stopped.
 
+`bootleg.build` will clean the remote workspace prior to copying the code over, to ensure that any files left from
+a previous build do not cause issues. The entire contents of the remote workspace are removed via `rm -rf *` from
+the root of the workspace. You can configure this behavior by setting the config option `clean_locations`, which
+takes a list of locations and passes them to `rm -rf` on the remote server. Relative paths will be interpreted relative
+to the workspace, absolute paths will be treated as is. Warning: this means that `config :clean_locations, ["/"]` would
+attempt to erase the entire root file system of your remote server. Be careful when altering `clean_locations` and never
+use a privileged user on your build server.
+
 ## Admin Commands
 
 Bootleg has a set of commands to check up on your running nodes:
@@ -183,8 +237,9 @@ Hooks are defined within `config/deploy.exs`. Hooks may be defined to trigger
 before or after a task. The following tasks are provided by Bootleg:
 
 1. `build` - build process for creating a release package
-  1. `compile` - compilation of your project
-  2. `generate_release` - generation of the release package
+  1. `clean` - cleans the remote workspace
+  2. `compile` - compilation of your project
+  3. `generate_release` - generation of the release package
 2. `deploy` - deploy of a release package
 3. `start` - starting of a release
 4. `stop` - stopping of a release
@@ -344,7 +399,7 @@ for building phoenix releases.
 # mix.exs
 def deps do
   [{:distillery, "~> 1.3"},
-  {:bootleg, "~> 0.3"},
+  {:bootleg, "~> 0.4"},
   {:bootleg_phoenix, "~> 0.1"}]
 end
 ```
@@ -353,7 +408,7 @@ For more about `bootleg_phoenix` see: https://github.com/labzero/bootleg_phoenix
 
 ## Sharing Tasks
 
-Sharing is a good thing. We love to share, espically awesome code we write. Bootleg supports loading
+Sharing is a good thing. We love to share, especially awesome code we write. Bootleg supports loading
 tasks from packages in a manner very similar to `Mix.Task`. Just define your module under `Bootleg.Tasks`,
 `use Bootleg.Task` and pass it a block of Bootleg DSL. The contents will be discovered and executed
 automatically at launch.

lib/bootleg/config.ex

@@ -497,6 +497,19 @@ defmodule Bootleg.Config do
     get_config(:version, Project.config[:version])
   end
 
+  @doc false
+  @spec env() :: any
+  def env do
+    get_config(:env, :production)
+  end
+
+  @doc false
+  @spec env(any) :: :ok
+  def env(env) do
+    {:ok, _} = Bootleg.Config.Agent.start_link(env)
+    config(:env, env)
+  end
+
   @doc false
   @spec split_roles_and_filters(atom | keyword) :: {[atom], keyword}
   defp split_roles_and_filters(role) do

lib/bootleg/config/agent.ex

@@ -6,9 +6,9 @@ defmodule Bootleg.Config.Agent do
   @typep data :: keyword
 
   @spec start_link() :: {:ok, pid}
-  def start_link do
+  def start_link(env \\ :production) do
     state_fn = fn ->
-      [roles: [], config: [], before_hooks: [], after_hooks: [], next_hook_number: 0]
+      [roles: [], config: [env: env], before_hooks: [], after_hooks: [], next_hook_number: 0]
     end
     case Agent.start_link(state_fn, name: Bootleg.Config.Agent) do
       {:error, {:already_started, pid}} -> {:ok, pid}

lib/bootleg/mix_task.ex

@@ -8,13 +8,15 @@ defmodule Bootleg.MixTask do
 
       @spec run(OptionParser.argv) :: :ok
       if is_atom(unquote(task)) && unquote(task) do
-        def run(_args) do
+        def run(args) do
+          Config.env(List.first(args) || :production)
           use Config
 
           invoke unquote(task)
         end
       else
-        def run(_args) do
+        def run(args) do
+          Config.env(List.first(args) || :production)
           :ok
         end
       end

lib/bootleg/tasks.ex

@@ -1,6 +1,6 @@
 defmodule Bootleg.Tasks do
   @moduledoc false
-  alias Bootleg.Config
+  alias Bootleg.{Config, UI}
 
   def load_tasks do
     use Config
@@ -16,7 +16,14 @@ defmodule Bootleg.Tasks do
 
     load_third_party()
 
-    Config.load("config/deploy.exs")
+    Config.load(Path.join("config", "deploy.exs"))
+    case Config.load(Path.join(["config", "deploy", "#{Config.env}.exs"])) do
+      {:error, :enoent} -> UI.warn("You are running in the `#{Config.env}` bootleg " <>
+        "environment but there is no configuration defined for that environment. " <>
+        "Create one at `config/deploy/#{Config.env}.exs` if you want to do additional " <>
+        "customization.")
+      val -> val
+    end
     :ok
   end
 

lib/bootleg/tasks/build.exs

@@ -7,17 +7,29 @@ end
 
 task :generate_release do
   UI.info "Generating release"
-  mix_env = Bootleg.Config.get_config(:mix_env, "prod")
+  mix_env = Keyword.get(Config.config(), :mix_env, "prod")
   remote :build do
     "MIX_ENV=#{mix_env} mix release"
   end
 end
 
 task :compile do
-  mix_env = Bootleg.Config.get_config(:mix_env, "prod")
+  mix_env = Keyword.get(Config.config(), :mix_env, "prod")
   UI.info "Compiling remote build"
   remote :build do
     "MIX_ENV=#{mix_env} mix deps.compile"
     "MIX_ENV=#{mix_env} mix compile"
   end
 end
+
+task :clean do
+  locations = config()
+    |> Keyword.get(:clean_locations, ["*"])
+    |> List.wrap
+    |> Enum.join(" ")
+  if locations != "" do
+    remote :build do
+      "rm -rvf #{locations}"
+    end
+  end
+end

lib/mix/tasks/init.ex

@@ -11,16 +11,19 @@ defmodule Mix.Tasks.Bootleg.Init do
 
   def run(_args) do
     deploy_file_path = Path.join(["config", "deploy.exs"])
+    deploy_dir_path = Path.join(["config", "deploy"])
+    production_file_path = Path.join(deploy_dir_path, "production.exs")
     Generator.create_directory("config")
     Generator.create_file(deploy_file_path, deploy_file_text())
+    Generator.create_directory(deploy_dir_path)
+    Generator.create_file(production_file_path, production_file_text())
   end
 
   Generator.embed_text(:deploy_file, """
   use Bootleg.Config
 
   # Configure the following roles to match your environment.
   # `build` defines what remote server your distillery release should be built on.
-  # `app` defines what remote servers your distillery release should be deployed and managed on.
   #
   # Some available options are:
   #  - `user`: ssh username to use for SSH authentication to the role's hosts
@@ -29,21 +32,38 @@ defmodule Mix.Tasks.Bootleg.Init do
   #  - `workspace`: remote file system path to be used for building and deploying this Elixir project
 
   role :build, "build.example.com", workspace: "/tmp/bootleg/build"
-  role :app, ["app1.example.com", "app2.example.com"], workspace: "/var/app/example"
 
-  # Phoenix has some extra build steps which can be defined as task after the compile step runs.
+  # Phoenix has some extra build steps such as asset digesting that need to be done during
+  # compilation. To have bootleeg handle that for you, include the additional package
+  # `bootleg_phoenix` to your `deps` list. This will automatically perform the additional steps
+  # required for building phoenix releases.
+  #
+  #  ```
+  #  # mix.exs
+  #  def deps do
+  #    [{:distillery, "~> 1.3"},
+  #    {:bootleg, "~> 0.4"},
+  #    {:bootleg_phoenix, "~> 0.1"}]
+  #  end
+  #  ```
+  # For more about `bootleg_phoenix` see: https://github.com/labzero/bootleg_phoenix
+
+  """)
+
+  Generator.embed_text(:production_file, """
+  use Bootleg.Config
+
+  # Configure the following roles to match your environment.
+  # `app` defines what remote servers your distillery release should be deployed and managed on.
   #
-  # Uncomment the following task definition if this is a Phoenix application. To learn more about 
-  # hooks and adding additional behavior to your deploy workflow, please refer to the bootleg 
-  # README which can be found at https://github.com/labzero/bootleg/blob/master/README.md
-
-  # after_task :compile do
-  #   remote :build do
-  #     "[ -f package.json ] && npm install || true"
-  #     "[ -f brunch-config.js ] && [ -d node_modules ] && ./node_modules/brunch/bin/brunch b -p || true"
-  #     "[ -d deps/phoenix ] && mix phoenix.digest || true"
-  #   end
-  # end
+  # Some available options are:
+  #  - `user`: ssh username to use for SSH authentication to the role's hosts
+  #  - `password`: password to be used for SSH authentication
+  #  - `identity`: local path to an identity file that will be used for SSH authentication instead of a password
+  #  - `workspace`: remote file system path to be used for building and deploying this Elixir project
+
+  role :app, ["app1.example.com", "app2.example.com"], workspace: "/var/app/example"
+
   """)
 
 end

lib/strategies/build/distillery.ex

@@ -17,6 +17,7 @@ defmodule Bootleg.Strategies.Build.Distillery do
 
     mix_env = Config.get_config(:mix_env, "prod")
     refspec = Config.get_config(:refspec, "master")
+    invoke :clean
     :ok = git_push(conn, refspec)
     git_reset_remote(conn, refspec)
     git_clean_remote(conn)

lib/ui.ex

@@ -52,6 +52,7 @@ defmodule Bootleg.UI do
   defp validate_verbosity(verbosity)
   defp validate_verbosity(:warning), do: :warning
   defp validate_verbosity(:debug), do: :debug
+  defp validate_verbosity(:silent), do: :silent
   defp validate_verbosity(_), do: :info
 
   defp verbosity_includes(setting, level)

mix.exs

@@ -1,7 +1,7 @@
 defmodule Bootleg.Mixfile do
   use Mix.Project
 
-  @version "0.3.0"
+  @version "0.4.0"
   @source "https://github.com/labzero/bootleg"
 
   def project do

test/bootleg/config/agent_test.exs

@@ -4,7 +4,7 @@ defmodule Bootleg.Config.AgentTest do
 
   test "stores values for retrieval" do
     {:ok, _} = Agent.start_link
-    assert Agent.get(:config) == []
+    assert Agent.get(:config) == [env: :production]
 
     Agent.put(:config, [key: :value, key2: :value])
     assert Agent.get(:config) == [key: :value, key2: :value]
@@ -13,8 +13,23 @@ defmodule Bootleg.Config.AgentTest do
     assert Agent.get(:config) == [key: :value, key2: :value, foo: :bar]
   end
 
-  test "startlink/0 ignores 'already started' errors" do
+  test "start_link/0 ignores 'already started' errors" do
     Agent.start_link
     assert {:ok, _} = Agent.start_link
   end
+
+  test "start_link/1 ignores 'already started' errors" do
+    Agent.start_link
+    assert {:ok, _} = Agent.start_link(:foo)
+  end
+
+  test "start_link/0 sets the environment to `production`" do
+    Agent.start_link
+    assert Agent.get(:config) == [env: :production]
+  end
+
+  test "start_link/1 sets the environment to the provided env" do
+    Agent.start_link(:bar)
+    assert Agent.get(:config) == [env: :bar]
+  end
 end