We removed our free Sandbox April 25th.
You can read more on our blog.



Unicorn is a preforking HTTP server written in Ruby. It’s designed to only serve fast clients on low-latency, high-bandwidth connection and take advantage of features in Unix/Unix-like kernels.

One of the big users of Unicorn is Github. They’re using a combination of Nginx and Unicorn to do code deployment with little downtime. You can read about their setup in this blog post.

This tutorial shows you how to switch from Passenger on dotCloud to using Unicorn. This tutorial does not cover configuring Unicorn in such a way that supports hot code deployment.

All the code presented here is also available on GitHub, at: https://github.com/johncosta/unicorn-on-dotcloud

dotCloud Build File

The dotCloud Build File, dotcloud.yml, describes our stack.

We declare a single “Ruby-Worker” service. We use a “Ruby-Worker” because it features two useful things for us:

  • a Ruby interpreter (obviously!)
  • a mechanism to install gems

The role and syntax of the dotCloud Build File is explained in further detail in the documentation, at http://docs.dotcloud.com/guides/build-file/.

  type: ruby-worker
    www: http

Gemfile & Dependencies

To tell dotCloud to automatically install the gem for Unicorn, we create a standard Gemfile. dotCloud will detect this, and automatically use bundler to install dependencies defined in the Gemfile.

See http://gembundler.com/gemfile.html for details about bundler and the Gemfile format.

# Gemfile

source 'http://rubygems.org'
gem "sinatra"
gem "unicorn"

Rack config file

Unicorn can load a Rack config file. We’ll use this start our Sinatra application.

# config.ru

require './helloworld'
run Sinatra::Application

Ruby Code

We now need an application that will respond to the http requests. We create a ruby script that defines one trivial endpoint /.

# helloworld.rb

require 'sinatra'

get '/' do
  "Hello World!\n"

Route Requests to Unicorn

By default, “Ruby-Workers” don’t have an http route. We’ll need to expand the dotcloud.yml file to add a http endpoint and to connect that endpoint to the running process.

  type: ruby-worker
    www: http
    unicorn: unicorn -d -I $GEM_PATH -p $PORT_WWW

Now we can push our application with dotcloud push and browse our service URL.