mina 0.3.0 → 0.3.1

data/support/guide.md

@@ -0,0 +1,297 @@
+
+User guide
+==========
+
+Setting up a project
+--------------------
+
+Let's deploy a project using Mina.
+
+### Step 1: Create a config/deploy.rb
+
+In your project, type `mina init` to create a sample of this file.
+
+    $ mina init
+    Created config/deploy.rb.
+
+This is just a Rake file with tasks! See [About deploy.rb](#about-deployrb) for 
+more info on what *deploy.rb* is. You will want to at least configure your
+server:
+
+~~~ ruby
+# config/deploy.rb
+set :user, 'username'
+set :domain, 'your.server.com'
+set :deploy_to, '/var/www/flipstack.com'
+...
+~~~
+
+### Step 2: Set up your server
+
+Make a directory in your server called `/var/www/flipstack.com` (in *deploy_to*)
+change it's ownership to the correct user.
+
+    $ ssh username@your.server.com
+
+    # Once in your server, create the deploy folder:
+    ~@your.server.com$ mkdir /var/www/flipstack.com
+    ~@your.server.com$ chown -R username /var/www/flipstack.com
+
+### Step 3: Run 'mina setup'
+
+Back at your computer, do `mina setup` to set up the [folder 
+structure](#directory_structure) in this path. This will connect to your server 
+via SSH and create the right directories.
+
+    $ mina setup
+    -----> Creating folders... done.
+
+See [directory structure](#directory_structure) for more info.
+
+### Step 4: Deploy!
+
+Use `mina deploy` to run the `deploy` task defined in *config/deploy.rb*.
+
+    $ mina deploy
+    -----> Deploying to 2012-06-12-040248
+           ...
+           Lots of things happening...
+           ...
+    -----> Done.
+
+About deploy.rb
+---------------
+
+The file `deploy.rb` is simply a Rakefile invoked by Rake. In fact, `mina` is
+mostly an alias that invokes Rake to load `deploy.rb`.
+
+~~~ ruby
+# Sample config/deploy.rb
+set :domain, 'your.server.com'
+
+task :restart do
+  queue 'sudo service restart apache'
+end
+~~~
+
+As it's all Rake, you can define tasks that you can invoke using `mina`. In this
+example, it provides the `mina restart` command.
+
+The magic of Mina is in the new commands it gives you.
+
+The `queue` command queues up Bash commands to be run on the remote server.
+If you invoke `mina restart`, it will invoke the task above and run the queued
+commands on the remote server `your.server.com` via SSH.
+
+See [the command queue](#the-command-queue) for more information on the *queue*
+command.
+
+The command queue
+-----------------
+
+At the heart of it, Mina is merely sugar on top of Rake to queue commands
+and execute them remotely at the end. Take a look at this minimal *deploy.rb*
+configuration:
+
+~~~ ruby
+# config/deploy.rb
+set :user, 'john'
+set :domain, 'flipstack.com'
+
+task :logs do
+  queue 'echo "Contents of the log file are as follows:"'
+  queue "tail -f /var/log/apache.log"
+end
+~~~
+
+Once you type `mina logs` in your terminal, it invokes the *queue*d commands
+remotely on the server using the command `ssh john@flipstack.com`.
+
+~~~ sh
+$ mina logs --simulate
+# Execute the following commands via
+# ssh john@flipstack.com:
+#
+echo "Contents of the log file are as follows:"
+tail -f /var/log/apache.log
+~~~
+
+Subtasks
+--------
+
+Mina provides the helper `invoke` to invoke other tasks from a
+task.
+
+~~~ ruby
+# config/deploy.rb
+task :down do
+  invoke :maintenance_on
+  invoke :restart
+end
+
+task :maintenance_on
+  queue 'touch maintenance.txt'
+end
+
+task :restart
+  queue 'sudo service restart apache'
+end
+~~~
+
+In this example above, if you type `mina down`, it simply invokes the other
+subtasks which queues up their commands. The commands will be run after
+everything.
+
+Directory structure
+-------------------
+
+The deploy procedures make the assumption that you have a folder like so:
+
+    /var/www/flipstack.com/     # The deploy_to path
+     |-  releases/              # Holds releases, one subdir per release
+     |   |- 1/
+     |   |- 2/
+     |   |- 3/
+     |   '- ...
+     |-  shared/                # Holds files shared between releases
+     |   |- logs/               # Log files are usually stored here
+     |   `- ...
+     '-  current/               # A symlink to the current release in releases/
+
+It also assumes that the `deploy_to` path is fully writeable/readable for the
+user we're going to SSH with.
+
+Deploying
+---------
+
+Mina provides the `deploy` command which *queue*s up a deploy script for
+you.
+
+~~~ ruby
+# config/deploy.rb
+set :domain, 'flipstack.com'
+set :user, 'flipstack'
+set :deploy_to, '/var/www/flipstack.com'
+set :repository, 'http://github.com/flipstack/flipstack.git'
+
+task :deploy do
+  deploy do
+    # Put things that prepare the empty release folder here.
+    # Commands queued here will be run on a new release directory.
+    invoke :'git:clone'
+    invoke :'bundle:install'
+
+    # These are instructions to start the app after it's been prepared.
+    to :launch do
+      queue 'touch tmp/restart.txt'
+    end
+
+    # This optional block defines how a broken release should be cleaned up.
+    to :clean do
+      queue 'log "failed deployment"'
+    end
+  end
+end
+~~~
+
+It works by capturing the *queue*d commands inside the block, wrapping them
+in a deploy script, then *queue*ing them back in.
+
+### How deploying works
+
+Here is an example of a deploy! (Note that some commands have been simplified
+to illustrate the point better.)
+
+### Step 1: Build it
+
+The deploy process builds a new temp folder with instructions you provide.
+In this example, it will do `git:clone` and `bundle:install`.
+
+    $ mina deploy --verbose
+    -----> Creating the build path
+           $ mkdir tmp/build-128293482394
+    -----> Cloning the Git repository
+           $ git clone https://github.com/flipstack/flipstack.git . -n --recursive
+           Cloning... done.
+    -----> Installing gem dependencies using Bundler
+           $ bundle install --without development:test
+           Using i18n (0.6.0)
+           Using multi_json (1.0.4)
+           ...
+           Your bundle is complete! It was installed to ./vendor/bundle
+
+### Step 2: Move it to releases
+
+Once the project has been built, it will be moved to `releases/`. A symlink
+called `current/` will be created to point to the active release.
+
+    $
+    -----> Moving to releases/4
+           $ mv "./tmp/build-128293482394" "releases/4"
+    -----> Symlinking to current
+           $ ln -nfs releases/4 current
+
+### Step 3: Launch it
+
+Invoke the commands queued up in the `to :launch` block. These often
+commands to restart the webserver process. Once this in complete, you're done!
+
+    $
+    -----> Launching
+           $ cd releases/4
+           $ sudo service nginx restart
+    -----> Done. Deployed v4
+
+### What about failure?
+
+If it fails at any point, the release path will be deleted. If any commands are
+queued using the `to :clean` block, they will be run. It will be as if nothing
+happened. Lets see what happens if a build fails:
+
+    $
+    -----> Launching
+           $ cd releases/4
+           $ sudo service nginx restart
+           Starting nginx... error: can't start service
+    -----> ERROR: Deploy failed.
+    -----> Cleaning up build
+           $ rm -rf tmp/build-128293482394
+    -----> Unlinking current
+           $ ln -nfs releases/3 current
+           OK
+
+Command line options
+--------------------
+
+Basic usage:
+
+    $ mina [OPTIONS] [TASKS] [VAR1=val VAR2=val ...]
+
+### Options
+
+* `-v` / `--verbose` - This will show commands being done on the server. Off by
+  default.
+
+* `-S` / `--simulate` - This will not invoke any SSH connections; instead, it
+  will simply output the script it builds.
+
+* `-t` / `--trace` - Show backtraces when errors occur.
+
+* `-f FILE` - Use a custom deploy.rb configuration.
+
+* `-V` / `--version` - Shows the current version.
+
+### Tasks
+
+There are many tasks available. See the [tasks reference](tasks/index.html), or 
+type `mina tasks`.
+
+### Variables
+
+You may specify additional variables in the `KEY=value` style, just like Rake.
+You can add as many variables as needed.
+
+    $ mina restart on=staging
+
+    # This sets the ENV['on'] variable to 'staging'.
+

data/support/index.html

@@ -0,0 +1,53 @@
+<html>
+<head>
+  <meta charset='utf-8'>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+  <meta name="viewport" content="width=device-width">
+
+  <title>Mina</title>
+
+  <!-- Flatdoc -->
+  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
+  <script src='http://rstacruz.github.io/flatdoc/v/0.8.0/legacy.js'></script>
+  <script src='http://rstacruz.github.io/flatdoc/v/0.8.0/flatdoc.js'></script>
+
+  <!-- Flatdoc theme -->
+  <link  href='http://rstacruz.github.io/flatdoc/v/0.8.0/theme-white/style.css' rel='stylesheet'>
+  <script src='http://rstacruz.github.io/flatdoc/v/0.8.0/theme-white/script.js'></script>
+
+  <!-- Meta -->
+  <meta content="Mina" property="og:title">
+  <meta content="Mina deployer tool." name="description">
+
+  <!-- Initializer -->
+  <script>
+    Flatdoc.run({
+      fetcher: location.hostname.match(/localhost/) ? Flatdoc.file('../Readme.md') : Flatdoc.github('nadarei/mina')
+    });
+  </script>
+</head>
+<body role='flatdoc'>
+
+  <div class='header'>
+    <div class='left'>
+      <h1>Mina</h1>
+      <ul>
+        <li><a href='https://github.com/nadarei/mina'>View on GitHub</a></li>
+        <li><a href='https://github.com/nadarei/mina/issues'>Issues</a></li>
+      </ul>
+    </div>
+    <div class='right'>
+      <!-- GitHub buttons: see http://ghbtns.com -->
+      <iframe src="http://ghbtns.com/github-btn.html?user=nadarei&amp;repo=mina&amp;type=watch&amp;count=true" allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe>
+    </div>
+  </div>
+
+  <div class='content-root'>
+    <div class='menubar'>
+      <div class='menu section' role='flatdoc-menu'></div>
+    </div>
+    <div role='flatdoc-content' class='content'></div>
+  </div>
+
+</body>
+</html>

data/support/to_md.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+c = /(?:#|\/\/)/  # Comment prefix
+lang = "ruby"     # Default language
+blocks = STDIN.read.scan(/(?:^[ \t]*#{c} [^\n]*\n)+/)       # Read contiguous comments
+blocks.map! { |s| s.gsub!(/(?:^|\n)+[ \t]*#{c} /, "\n") }   # Strip out prefixes
+
+# Code blocks
+md = blocks.join("")
+md.gsub!(/((?:^    .*\n+)+)/) { |f| "~~~ #{lang}\n" + f.gsub(/^    /, '').gsub(/\s*$/, '') + "\n~~~\n\n" }
+
+puts md

data/test_env/config/deploy.rb

@@ -25,6 +25,8 @@ set :deploy_to, "#{Dir.pwd}/deploy"
 set :repository, "#{Mina.root_path}"
 set :shared_paths, ['config/database.yml']
 
+set :keep_releases, 2
+
 task :environment do
   queue %[echo "-----> Loading env"]
 end

metadata

@@ -1,67 +1,81 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: mina
-version: !ruby/object:Gem::Version
-  version: 0.3.0
+version: !ruby/object:Gem::Version 
+  hash: 17
+  prerelease: 
+  segments: 
+  - 0
+  - 3
+  - 1
+  version: 0.3.1
 platform: ruby
-authors:
+authors: 
 - Rico Sta. Cruz
 - Michael Galero
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-10 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2014-10-17 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: open4
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: open4
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 3
+        - 4
+        version: 1.3.4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
   name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :development
+  version_requirements: *id003
 description: Really fast deployer and server automation tool.
-email:
+email: 
 - rico@nadarei.co
 - mikong@nadarei.co
-executables:
+executables: 
 - mina
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .rspec
 - .travis.yml
@@ -69,13 +83,16 @@ files:
 - Gemfile
 - HISTORY.md
 - LICENSE
-- README.md
+- Makefile
+- Notes.md
 - Rakefile
+- Readme.md
 - bin/mina
 - data/deploy.rb
 - data/deploy.sh.erb
 - lib/mina.rb
 - lib/mina/bundler.rb
+- lib/mina/chruby.rb
 - lib/mina/default.rb
 - lib/mina/deploy.rb
 - lib/mina/deploy_helpers.rb
@@ -97,6 +114,7 @@ files:
 - manual/modules.md
 - mina.gemspec
 - spec/command_helper.rb
+- spec/commands/cleanup_spec.rb
 - spec/commands/command_spec.rb
 - spec/commands/custom_config_spec.rb
 - spec/commands/deploy_spec.rb
@@ -111,31 +129,48 @@ files:
 - spec/dsl/to_spec.rb
 - spec/fixtures/custom_file_env/custom_deploy.rb
 - spec/fixtures/empty_env/config/deploy.rb
+- spec/helpers/exec_helper_spec.rb
 - spec/helpers/output_helper_spec.rb
 - spec/spec_helper.rb
+- support/Readme-footer.md
+- support/Readme-header.md
+- support/guide.md
+- support/index.html
+- support/to_md.rb
 - test_env/config/deploy.rb
+has_rdoc: true
 homepage: http://github.com/nadarei/mina
 licenses: []
-metadata: {}
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
-  requirements:
-  - - '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
-  requirements:
-  - - '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 2.0.2
+rubygems_version: 1.6.2
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Really fast deployer and server automation tool.
 test_files: []
-has_rdoc: 
+

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 48b10c2f04fe8cd4a81515ad180b07e988e30315
-  data.tar.gz: a6eb8c996ad4128d29096ce7f7307f007e0bc207
-SHA512:
-  metadata.gz: 58ff29681d74382796c04253d9d29d7af8eb4c10b13788d6e66004975cd1c520a1b764de1f21b9cfd62e57e59a521f30e3c948c6b8eccfb8a8397e9560d1bb70
-  data.tar.gz: e446b721204e02b30683df7f6bc785098bd809d83b7a0bf48b9c725d77666acaebd03138b877447096e9b355b0726effb661fe61cda7974e7342eb397591ece9