Inploy: The No Brainer Deployment Solution

This guest post is contributed by Fabio Akita, who works as Project Manager for GoNow Tecnologia, in Brazil, leading Ruby on Rails projects. He worked for Locaweb, the largest web hosting company in Latin America where he helped implement the support for Rails in a shared web hosting for the first time. He and Locaweb also joined forces to create the successful Rails Summit Conference which now changed to RubyConf Brasil. He worked as Brazil Rails Practice Manager for Surgeworks LLC. Fabio travelled all around Brazil evangelizing the Ruby on Rails Ecosystem and modern Agile-based best practices for project management. He blogs at AkitaOnRails.com.

Ruby on Rails deployment is something that has been constantly evolving over the years. For many people “deployment” still means connecting through FTP to a remote server and dragging and dropping a bunch of files to a folder.

You can certainly do something similar with Rails. Products such as Phusion Passenger for Apache/Nginx makes this process easier: you just define a folder and drop files in there.

Problem is, this is usually not something you do just once. You will fix bugs, improve your code, add new features, and you will keep on redeploying, overwriting old files and so on. The process of manually moving files around for deployment, even for small websites, can lead to unexpected human failure and, so, sleep deprivation, which is bad. So this process is not recommended and considered a big liability. Rule of thumb: thou shall not update production servers manually.

We all had bad experiences like this before. We also know that the best route for a safe deployment is proper automation. System administrators should always strive to automate as much as possible. If you are repeating trivial tasks manually, you are probably doing it wrong.

We have the hardcore tools such as Puppet and Chef, but for small to medium deployments we always relied on the good old Capistrano. For a long time it was the de facto way to automate deployments, even to many machines. It was able to do the initial setup, push new versions of your apps to your production machines reliably and even to maintain old versions so you could easily rollback to a working version with a single command.

Capistrano, created and maintained by Rails Core Team Alumni Jamis Buck, was a great tool. It helped perfect the Net::SSH libraries so you can script SSH connections through Ruby.

But we learned new tricks. One big change since then is that we started adopting Git as the version control system of choice. We can leverage the same thing that Capistrano provided in a much simpler way leveraging tools such as Git to simplify the whole process.

Thus, Inploy was born, by the skillful hands of Diego Carrion. His intentions were clear: Capistrano is way big and complex for simpler deployments. You need to customize too much for stuff that could have been the default way of doing things. Convention over Configuration, that’s what Inploy is all about.

Right now it supports Mongrel, Thin, Passenger and Unicorn. It assumes you are using Git. It already defines many tasks that can be executed either remotely or locally, such as restarting the web application server’s processes or running Rails’ database migrations. It also supports templates, so that you can reuse a specific deployment strategy across many hosting solutions. It doesn’t have nearly as many options as Capistrano, so it is not a full replacement. This is an alternative for small to medium deployments.

To be a competent Ruby on Rails developer, we always assume that you already know the basics of system administration at the very least, such as installing and hardening your own Linux box, installing and configuring a web server, installing a database system, setting up your firewall and so on, so I won’t detail into those simple tasks.

Because Inploy aims for simplicity, even its source code is very minimal and you can skim through it very easily. So I recommend you take a look at it to understand its features and how it is organized. Just to give you an idea, the entire project, if you count raw lines and add the specs and tests, has less than 1.5k lines of code.

You can install Inploy as a gem:

gem install inploy

Then, in your Rails project, you need to create a config/deploy.rb file. You should have something like this:

application = "signal"
repository = 'git://github.com/dcrec1/signal.git'
hosts = ['hooters', 'geni']

#path = '/var/local/apps'
#user = 'deploy'
#ssh_opts = ''
#branch = 'master'
#sudo = false
#cache_dirs = %w(public/cache)
#skip_steps = nil
#app_folder = nil

The best way to understand these options is to actually read the lib/deploy.rb from the Inploy project, which has only 100 lines of code. Then you will start figuring out where and how those variables are used. For example:

def remote_setup
  remote_run "cd #{path} && #{@sudo}git clone --depth 1 #{repository} #{application} && cd #{application_folder} #{checkout}#{bundle} && #{@sudo}rake inploy:local:setup environment=#{environment}#{skip_steps_cmd}"
end

The remote_run method will connect to all the hosts defined in the hosts array and execute the following command. Then the variables are used to create the git clone task. Notice that it also runs the inploy:local:setup Rake task. It is there if you need – for some reason – to manually log in the server and run rake inploy:local:setup.

The DSL is very simple and is entirely based on Module Mixins. Therefore you can also create Templates, which are simple Ruby Modules that override the default methods. That way you can customize Inploy for any specific Web Hosting provider and mix in to your config/deploy.rb file.

Once you configure the config/deploy.rb file, you will have to run this command just once:

inploy setup

This will connect to all the hosts specified in the configuration file, and make the initial setups.

Then, every time you need to redeploy, you just run this command:

inploy

Under the hood, the setup task will create a git clone from the git repository you specified (make sure both your development machine and your production server have access to this git repository). Then, when you redeploy it is just a matter of running git pull to get the newest code and run maintenance tasks such as db:migrate

There are a lot of tasks Inploy already automate out of the box such as running asset packager if you are using it, informing HopToad if you’re using it and so on. You can override the before_restarting_server if you want to add more update tasks or you can override the entire after_update_code method to add your own sequence of update tasks.

The most current version also includes a Rails 3 Push template strategy. You can simply add this line at the top of your config/deploy.rb file:

template = "rails3_push"

Now the inploy setup command will configure an inplace Git repository approach. It will create a Git repository directly on your production machine. Then every time you run the inploy command it will git push your new commits to this repository. Then, there is no step 3! It doesn’t need to git pull because you already pushed to the location where your web server is already pointing at. This is a very simple, Heroku-like, kind of deployment.

And if you have an empty box, with only SSH enabled, you can still automate the installation of packages and other stuff through a web available script. For example, let’s say you have a web server that contains recipes (Bash scripts) at http://myserver.com/myscript. You can execute it on your empty box like this:

inploy install from=http://myserver.com/myscript

And then you can do inploy setup and inploy as usual.

One of most notable omissions from Inploy, compared to Capistrano, is the equivalent to cap rollback. The entire directory structure and symlink strategy used by Capistrano is done in such a way to make it easier to rollback to previous versions by creating time stamped folders and symlinks to point to the current version.

It is a clever strategy, but maybe a bit too much for small/medium projects. If you already have Git and you already tag the versions properly, it is only a matter of git checkout old_tag to rollback to a previous version.

Inploy, by itself, does not implement a rollback option because it was never requested so, which means that this is a feature that people rarely use. Most of the time, if you do proper testing and continuous integration, you can safely assume that it wouldn’t break in production. This is not 100%, of course, but it means that the chance of you needing a rollback feature is drastically diminished.

As you can see, Inploy is a very pragmatic, thin wrapper around SSH automation, that is very easy to set up and use. Try to study the source code, you will be surprised to be able to understand it very easily and quickly customize it for your particular needs.

I hope you found this article valuable. Feel free to ask questions and give feedback in the comments section of this post. Thanks!

Do read these awesome Guest Posts:

• Do YOU know Ruby’s ‘Chainsaw’ method?
• An introduction to eventmachine, and how to avoid callback spaghetti
• The Testing Mindset
• An Introduction to Desktop Apps with Ruby
• The Ruby movement
• Almost everything is an object (and everything is almost an object!)
• So… you’re new to Ruby!
• Incorporating Web APIs to spark computer programming exercises
• 14 Ways To Have Fun Coding Ruby
• Writing modular web applications with Rack
• How to Learn Ruby (or any programming language)

Fabio Akita’s “AkitaOnRails” series at RubyLearning.com, for would-be Ruby developers, has been quite a hit. Today in another article, Fabio talks in depth about Ruby’s Blocks/Closures, This is a rather long article but well worth the time invested in reading it. The entire source code for the programs in this article is available here.

Fabio Akita is a Brazilian Rails enthusiast, also known online as “AkitaOnRails”. He regularly write posts on his own blog and had published the very first book tailored for the Brazilian audience called “Repensando a Web com Rails”. He is now a full-time Ruby on Rails developer working as Brazil Rails Practice Manager for the Utah company Surgeworks LLC.

Note: You may want to brush up on Ruby Blocks and Procs before going through Fabio’s article.

Fabio>> There is no Rubyism more difficult to explain, than a Closure. I could write an entire book about it. Instead of boring everyone to death with academics, I’ll try to focus only on what one really needs for day-to-day activities.

Let’s start with an example:

# program1.rb
for i in [1,2,3,4]
  puts i
end

a = 0
b = [1,2,3,4]
while a < b.length
  puts b[a]
  a += 1
end

These are very simple iterators, similar to what we have in several languages. The first one with a ‘for‘ construct and the second with the familiar ‘while‘ statement. Nothing fancy here. But let’s see another way of accomplishing the same thing in Ruby:

# program2.rb
[1,2,3,4].each { |i| puts i }

[1,2,3,4].each do |i|
  puts i
end

Not too shabby, simpler and elegant, but that’s where people start gasping. The pipes notation is particularly threatening for non-starters. Both the brackets and the do..end notations define an enclosed piece of code that we name as ‘blocks’ or ‘closures’. What’s between the pipes are like parameters to a method. It ‘feels’ like this pseudo-code:

def unnamed_method(i)
  puts i
end

[1,2,3,4].each(unnamed_method)

This is not valid Ruby code, of course. That’s similar to what we would do in C# with delegates. We have something similar in JavaScript (using the “Prototype”:http://www.prototypejs.org/api/enumerable/each library):

[1,2,3,4].each(function(i) {
  alert(i);
});

In Javascript functions are first-class citizens of the language and they can be defined anonymously (without a name), and then passed as parameters to another function. We can manipulate and move functions all over the place.

Ruby doesn’t have methods as first-class citizens. We actually can extract a method from an object and wrap it around a ‘Method‘ object, but it holds the context of its object, so it is not independent.

# program3.rb
class Test
  def initialize
    @hello = "Hello!"
  end
  def say
    @hello
  end
end

m = Test.new.method(:say)
puts m.call # => "Hello!"
puts m.class # => "Method"

Here, we extracted the :say method from the instantiated Test instance. Notice that we can now manipulate the method as a normal object. Whenever we send the ‘call‘ message to the method object, it runs as if it was being executed from the context of the original object (Test.new.say). In the above example the second last statement would successfully print “Hello!”, as stored in the local instance variable @hello.

Although simple, we don’t do this very often. That’s because this method is bound to the original object’s context and we don’t usually want that: it would be nice to have an independent block of code. So, let’s create one very simple block of code referenced by a variable:

# program4.rb
c = lambda { |i| puts i }
c.call(1) # => 1
c.call(2) # => 2

The ‘lambda‘ keyword encloses the code within brackets as an object block, an instance of the Proc class. This object responds to the ‘call‘ method. In the last two statements we pass parameters to the ‘call‘ method and it goes to the ‘i’ variable defined within pipes inside the block. So, it acts as an independent entity, detached from any particular class. Let’s test it:

# program5.rb
c = lambda { |i| puts i }

class Test
  def say(block)
    block.call(self.class)
  end
end

c.call(self.class) # => Object
Test.new.say(c)    # => Test

We’re using the same block defined above in the variable ‘c’. After the definition of the Test class, we call the block object passing ‘self.class’ and it returns Object as a result. Then, we call the :say method from inside an instance of the Test class. The :say method calls the block giving the inner ‘self.class’ as a block parameter. In this case it prints out ‘Test’ instead of ‘Object‘, meaning that the block binds itself to the enclosing scope. That’s one difference between a block and a detached object method.

In many ways, Blocks resembles anonymous functions from Javascript, anonymous delegates from C#, anonymous inner classes from Java. This is a very useful construct that was primarily created to better handle iterators. For instance:

# program6.rb
[1,2,3,4].reverse_each { |i| puts i }
# => 4
# => 3
# => 2
# => 1

Now, this is different from the Array’s ‘each‘ method we used before. ‘reverse_each‘ navigates backwards through the Array’s elements. It gets each element and passes it into the ‘i’ variable, set as a parameter for the block defined within brackets.

In languages like Java, everything has to be defined through an interface. Enumerators are no different, and we have interfaces like ‘Iterator’. This method defines simple methods as ‘hasNext()’ and ‘next()’. But what if we actually need something as a reverse iterator? Now we’re on our own. What if we need something more complicated like an iterator that only walks through even elements? In Ruby we can define such a method like this:

# program7.rb
class Array
  def even
    i = 0
    while i < self.size
      yield(self[i]) if i % 2 == 0
      i += 1
    end
  end
end

[1,2,3,4,5,6].even { |i| puts i }
# => 1
# => 3
# => 5

First of all, remember that Ruby’s classes are all open, so we can easily redefine the standard Array class and append new methods to it. Now pay attention to the ‘even’ method. We implement it the usual way with a ‘while’ loop. But the interesting bit is the ‘yield‘ keyword. Pretend that it works like a *wildcard placeholder* for blocks. In the example, when we pass the ‘self[i]‘ value as its parameter, we’re actually passing this value to the ‘i’ parameter in the block.

We can rewrite this method in a slightly different way but with the same behavior:

# program8.rb
class Array
  def even(&code)
    i = 0
    while i < self.size
      code.call( self[i] ) if i % 2 == 0
      i += 1
    end
  end
end

So, now we explicitly defined that the ‘even’ method expects to receive a block, converting it to the ‘code’ parameter. Then, inside it we send the ‘call‘ method to ‘code’ and pass ‘self[i]‘ as its parameter. The result is exactly the same as using the yield keyword.

We can still do it differently:

# program9.rb
class Array
  def even(block)
    i = 0
    while i < self.size
      block.call( self[i] ) if i % 2 == 0
      i += 1
    end
  end
end

Now we’re doing it without the ampersand in the parameter. In the previous example, the ampersand operator ‘captures’ a block into a Proc instance object. In the latest example, the ‘even’ method expects to directly receive a Proc object, like this:

# program10.rb
class Array
  def even(block)
    i = 0
    while i < self.size
      block.call( self[i] ) if i % 2 == 0
      i += 1
    end
  end
end
c = lambda { |i| puts i }
[1,2,3,4,5,6].even( c )

Let’s go back to the Array’s ‘each‘ method as we displayed before:

c = lambda { |i| puts i }
[1,2,3,4].each( &c )

A little bit different, because the ‘each‘ method doesn’t expect a Proc object as a parameter, but an actual Block. So we use the ampersand before the Proc instance variable and it kind of ‘expands’ it back into a ‘raw’ code block, so that the ‘even’ method can ‘yield’ it inside, instead of executing through the ‘call‘ method.

This usage of a Proc object is not as elegant as just passing a Block, but with this construct we are storing code within an object. We can define a method that receives as many blocks as we need, for instance:

# program11.rb
def foo(name, block1, block2)
  block1.call
  puts name
  block2.call
end

foo "Fabio", lambda { puts "Hello" }, lambda { puts "World" }

This example receives a normal parameter and 2 blocks instead of one. We can pass blocks as enclosed Proc objects in the parameters list as we would do with any other kind of object. We usually don’t need that many discrete blocks inside a single method. The most usual style is:

# program12.rb
def foo( param1, param2 )
  # do something
  some_param = 1
  yield( some_param ) if block_given?
end

foo(1, 2) do |some_param|
  # do something
end

So we define a normal method, with normal parameters. But inside it we ask ‘block_given?‘. If positive, it ‘yields’ its block passing some parameter to it (of course, parameters are optional, and you can pass as many parameters as you want to a block, even zero parameters).

We call the defined method as usual, passing a block at the end of the method call. By the way, here’s another way of defining a block: using the do .. end construct. There is no strict rule, but we reserve the brackets notation when the block is small and we can state it in a single line, and the do .. end notation when we have blocks with multiple statements inside.

There’s a gotcha:

foo a, b do |some_param|
  # do something
end

foo a, b { |some_param| # do something }

Both brackets and do .. end constructs define blocks, so at first glance the 2 above statements seems to do the same thing. But the gotcha is that in Ruby parenthesis are optional, and we’re not using them here.

In the first statement the block is assumed to be passed to the ‘foo’ method as expected, with ‘a’ and ‘b’ as normal parameters. But the second statement guesses that ‘b’ is a method and tries to pass the block to it. The recommendation is: if you have a method that needs both parameters and a block, enclose the parameters within parenthesis to avoid ambiguities.

We now understand that Blocks are pieces of code that can be exchanged between method calls, as parameters or returned values. But there is more to it:

# program13.rb
c = lambda { |i| puts i }
c = Proc.new { |i| puts i }
c = proc { |i| puts i }

The above 3 statements do the same thing: instantiate a block object. ‘proc’ is an alias for ‘lambda‘ and they work slightly different than ‘Proc.new‘. In Ruby 1.9, ‘proc’ will probably be an alias for ‘Proc.new‘ instead.

Keywords to keep in mind are:

• lambda/Proc.new – encloses a bunch of code inside a Proc instance.
• & – ampersand, either captures a ‘raw’ code block into a Proc object or expands the Proc object as a ‘raw’ block.
• {}/do..end – defines a code block.
• || – pipes, defines the parameters of a block. If you don’t need any, just omit the pipes altogether.

So, some people misinterpret Blocks as a simple function pointer, or something like Java’s anonymous inner class. That’s not the case: and here we finally boil down to “Closures”. Ruby Blocks are Closures. The words ‘blocks’ and ‘closures’ mean the same thing in Ruby.

Ruby Blocks can enclose not only code and it’s own inner local variables, but it can enclose the surrounding context variables. That’s why it is called a ‘closure’. Let’s see an example:

# program14.rb
def greetings_factory(prefix)
  Proc.new { |name| "#{prefix}, #{name} !"}
end

birthday = greetings_factory("Happy Birthday")
xmas = greetings_factory("Merry XMas")

puts birthday.call("David") # => "Happy Birthday, David !"
puts xmas.call("Matz")      # => "Merry XMas, Matz !"

The first thing is a method definition for ‘greetings_factory’. It gets a prefix as a parameter and returns a Proc object, whose inner parameter is a name. So far so good.

The second part defines 2 Proc instances, one for birthday and another for christmas. Notice that we pass 2 different prefixes into the ‘greetings_factory’ method. The different values are ‘closed’ within Block. So, when we later call them, we see how differently they behave: they actually stored the latest state within itself. So each block stored the ‘prefix’ variable passed before, while still accepting the ‘name’ parameter within the Block.

Keep in mind that every Ruby Block is a Closure, that’s why this construct actually works:

# program15.rb
list = []
[1,2,3,4].each do |i|
  list << i * 2
end
puts list.inspect # => [2, 4, 6, 8]

So, we defined a ‘list’ array *before* we create the iterator block. Then, inside the block we refer to the external ‘list’ array and populate it. In Java, this would’ve been a final variable, but in Ruby there is no such limitation.

You’d want to be very careful about the surroundings of your block: do not define variables that’s going to be used inside the blocks too early in the code. Try to keep dependencies nearby, like in the above example where the ‘list’ Array is defined right before the iterator itself.

Iterators get a big boost because we’re not limited to a hard Interface. We can add whatever methods we need, like ‘each’, ‘reverse_each’, ‘collect’, ‘select’ and so on. Each one of them can receive a block and pass one element at a time to the user-defined block.

Another very important usage is to enclose widely used code patterns. For example, Rails has the following construct to use database transactions:

User.transaction do
  u = User.new(:login => 'admin')
  u.save!
end

‘User’ would be the ActiveRecord instance. One example of the structure for the model’s ‘transaction’ class method would resemble this structure:

class ActiveRecord::Base
  def self.transaction
    begin
      ActiveRecord::Base.establish_connection
      yield if block_given?
    rescue => e
      RAILS_DEFAULT_LOGGER.error e
    ensure
      ActiveRecord::Base.remove_connection
    end
  end
end

This means: open the database then try to ‘yield’ the block if provided. If anything wrong happens, get the error message and log it. Finally ensure that the connection is dropped after all this.

ActiveRecord doesn’t open and close connections this often, but you get the idea. But this is an overall big picture of one way to avoid repetition and the extraction of common code patterns. So it’s clever to encapsulate common functionality and place in a placeholder for user-defined code in-between.

The File.open method does the same thing: it takes responsibility of properly opening files, yielding the user block and ensuring that the file is closed without the user having to manually do this kind of house cleaning.

The most important “concept”:http://martinfowler.com/bliki/Closure.html is that Blocks helps hiding implementation details. We don’t want to know the inner details of a list iterator, or how a transaction works. We just need to focus on the business logic itself, trapped within a Block.

We described here a lot of stuff, and I think it covers the basics. Enough to actually read some of the Rails source-code and get acquainted for closure’s modus operandi. Hope you enjoyed this article!

Thank you Fabio for showing us a different perspective on Ruby Blocks. In case you have any queries, questions on this article, kindly post your questions here and Fabio would be glad to answer.