This is part follow-up to my previous two posts and part a response to some questions I’ve seen on the Neo4j.rb group about deployment. A big drawback of using Neo4j.rb is that it cannot be deployed to Heroku, since it uses an embedded database and not Neo4j’s REST API. However, setting up a server to host your application isn’t as hard as you might think and you’ll get much better performance. The following is how I do it with Chef and Capistrano.

Before we start:

• I use Digital Ocean for VPS hosting, but Linode and EC2 are also great.
• I used Ubuntu 12.04 64-bit on this. I don’t think there’s anything that would break this on other Linux distros, but I’m not sure…
• This uses Torquebox for an application server because it’s awesome.
• In order to keep it simple, this demo also uses Nginx as a reverse proxy. If you want mod_cluster support, you’ll have to use Apache2. Have a look at this.

Part I: Server by Chef

A copy of the Chef recipe is here. I’ll be using knife-solo to keep it simple. Let’s clone this:

1
2
3

$ git clone https://github.com/cfitz/neo4j-torquebox-kitchen
$ cd neo4j-torquebox-kitchen
$ bundle 

First, edit the nodes/neo4j-example.json file to change the “server_name” and “application_name” to match the domain name of your server. Or you can just us IP address if you don’t have a name. Just note that for the rest of this blog, I’m going to referrer to the application as “neo4j-demo-app.com”.

The next thing you’re going to need to change is the data_bags/users/torquebox.json file. This is the configuration for the torquebox user that Chef will create on the server. You’ll need to make a new encrypted password (this one in the demo code is just “password”). To do that, run:

1
2
3

$ openssl passwd -1 "theplaintextpassword"
or
mkpasswd -m sha-512

Copy and paste the output into the JSON’s password key. You’ll also want to add your ssh_key to this file. And you can delete the homesick_castles entry if you want, as it will install a dotfile in your user’s home directory (cool, but not essential. If you want to use this, I’d suggest forking it and editing it to your liking). You can also add any other users that you want by simply replicating this JSON file, changing the values, and adding the username to the default.users array in site-cookbooks/neo4j-example/attributes/default.rb .

Once you have your node and users configured, we can run this:

1
2

$ bundle exec librarian-chef install # this is like a bundle command to update our recipes.
$ bundle exec knife solo bootstrap root@neo4j-demo-app.com nodes/neo4j-example.json 

Change the name of the server to match your server name or IP.

This might take awhile, since we’re having to install a few packages. Among other things, this will:

• Install a user named torquebox.
• Download and install torquebox 2.3.2 into /opt/torquebox
• Install and configure Nginx as a reverse proxy
• Locks down ssh to not allow password authentication and not allow root user access.
• Sets a minimal iptables configuration to only allow ports 80, 443, and 22.
• Install fail2ban, vim, tmux, git, and some other packages, which I always like to have.

If you go to your servers root URL, you should get a “502 Bad Gateway” from Nginx. This is good news for now…so let’s deploy an app!

Part II: App by Rails

I made this demo application as a reference by following the Complete Example on the Neo4j.rb wiki with a couple of gems added. These are:

1
2
3
4
5
6
7
8
9

gem "neo4j", "2.3.0"
gem 'neo4j-community'
gem 'neo4j-advanced'
gem 'neo4j-enterprise'
gem "torquebox-server"
gem "torquebox"
gem "torquebox-rake-support"
gem 'torquebox-capistrano-support', :group => :development
gem 'capistrano'

Add those gems to your application, bundle it, and you’ll be ready to run it. But let’s take a brief detour…

Intermission: Run Your App Locally with Torquebox

The torquebox-server gem has an embedded version of Torquebox that you can use to run your application. To do that, run this command:

1
2

$ bundle exec torquebox deploy # this "deploys" your application by generating a torquebox knobfile.
$ bundle exec torquebox run 

Go to http://localhost:8080/users and you should see you’re application.

Back to deploying it.

Part III: Deployment by Capistrano

First, the easiest way to deploy with Capistrano is to check your application into version control, like Github.

1
2
3
4
5

$ git init
$ git add .
$ git commit -m "initial commit"
$ git remote add origin git@github.com:cfitz/neo4j-demo-app.git
$ git push origin master

To setup Capistrano, run this command from your Rails root:

1

$ bundle exec capify .

This add a few files to your rails application. First is Capfile. Make sure to comment our “load ‘deploy/assets”.

Now look at the config/deploy.rb file (see the inline comments on how this all works):

You’ll have to change a few values to match your server name and application name. When you’re ready to deploy, run:

1
2

$ bundle exec cap deploy:setup # this creates the folder structure for your application. Only do it once on your initial run
$ bundle exec cap deploy

This will:

• Check your application out in Git and deploy it to /opt/apps/neo4j-demo-app.com
• Compile your assets locally and scp them to the server.
• Deploy a torquebox knobfile and start your application.

You should not have to start torquebox on deploys, but if you want to control your server, you can do that with Rake:

1
2
3

$  bundle exec cap deploy:restart 
$  bundle exec cap deploy:start
$  bundle exec cap deploy:stop

Now you should go to http://neo4j-demo-app.com/users (or whatever your URL is) and see your application. Any time you want to update your code, simply check it into git and run cap deploy.

This might be more work than Heroku, but you’ll get much better performance off the bat and it will not cost you an arm and a leg when you want to scale out.

Suggestions / Questions always welcome.

Alright, so as the title suggests, this is the second part of an explanation of how I am using Chef and Capistrano to deploy Rails applications. Part 1 can be found here.

Part 1 was all about using Chef to provision and configure the server. This has all been setup to show how to deploy a Blacklight application, which uses Solr for indexing, but I hope it’s easy to see how you can tailor this to work with your application’s needs.

This part is all about using Capistrano to deploy the application to the server. This will probably be much easier to follow along, as it’s not really that complicated. I do a couple of tricky things to have zero downtime deploys and local asset compilation, but I try to make it really obvious where I’m being essentially cute and when I’m being unessentially cute.

First, this all assumes you have a Rails application. You can set one up using the Blacklight quickstart or whatever you want, but you need to have an app. For your referencing pleasure, you can look at this really simple Blacklight application which I setup for this blog. And for Capistrno, you’ll need to check this application into version control.

Now, remember in Part I, I set up the rails_application recipe to deploy a database.yml to the server with the database information already configured. So we don’t need to really do anything with the database.yml.

Unicorn

For production, I like to use Unicorn with Nginx serving as a reverse proxy. To configure Unicorn, we need to add a config/unicorn.rb file:

and be sure to check this into version control…

Setup Capistrano

Take a look at the Gemfile. You will need to add the capistrano, capistrano-ext, rvm-capistrano, capistrano-unicorn, unicorn gems and bundle that.

Now we need to setup Capistrano for the project:

1

$ bundle exec capify .

This will create a file at Capfile and a ./config/deploy.rb file. For this project, we can leave the Capfile as it is, since we’re going to do asset compiling locally then scp the results to the server. But, if we wanted to make the server compile our assets, we can change that in the Capfile.

I usually like to use the multi-stage feature of Capistrano, since I usually have a staging and production environment in play. To do this, make a config/deploy directory. To configure your staging server, you make a file in this directory call staging.rb

1
2
3
4

set :server_ip, "catalog-dev.wmu.se"
server server_ip, :app, :web, :primary => true
set :rails_env, 'production'
set :branch, 'master'

All the action takes place in the ./config/deploy.rb file:

Once this is in place, we can deploy our application:

1
2
3

$ cap deploy:setup
$ cap deploy:migrate
$ cap deploy COMPILE_ASSETS=true

The COMPILE_ASSETS option forces Capistrano to compile the assets. The default action will only compile if there have been changes made to your assets. On the initial run, make sure you set the COMPILE_ASSETS, since the default will not compile on the first run since it will not find any changes in your history.

The following is a merging of a few blog posts and gists, primarily here, here, and here. I try and capture how to provision a server with Chef & Knife and deploy a Rails application using Capistrano that uses Unicorn with Nginx, a small MySQL server, and a Solr index running in Jetty. Pretty much your standard Blacklight stack.

Have a look and let me know what you think. Especially suggestions to make things better.

Some things starting off:

• You can see the Chef code at https://github.com/cfitz/catalog-kitchen/ and the app code at https://github.com/cfitz/blacklight_app.git .
• There’s no shortage of hosting providers, and many of them have Knife plugins. EC2, Linode, EngineYard … they’re all great. I like Digital Ocean, so that’s what I’m using here.
• For this demo, the application is named “catalog” and will be hosted on catalog-dev.wmu.se.
• I’m using librarian for dependencies.
• This is all tailored to deploying a Blacklight application, which requires some specific Solr configuration. I try to make it obvious where that happens.
• I’m still using RVM because I suck.

Provision the server

Before I can do anything, I have to install the knife-solo and digital ocean gems:

1

$ gem install knife-solo knife-digital_ocean

And now I make our Chef project (or “kitchen”). As I said, the project’s name is “catalog”…

1

$ knife solo init --librarian catalog-kitchen

As Shawn Dahlen states, even when running Chef solo it’s a good idea to check your Chef project into a Git repository, which allows you to tag and branch your releases. So, I do that:

1
2
3
4
5

$ cd catalog-kitchen
$ git init
$ git add .
$ git commit -m "init commit"
$ git checkout -b dev

For provising our servers, we can do that either on Digital Ocean’s web interface, or we can use Knife. To use knife, find your APIs keys in the Digital Ocean dashboard and add them to a file named .chef/knife.rb.

.. and I always add this to my .gitignore file.

1

$ echo .chef/ >> .gitignore

It’s also a good idea to upload your public SSH key to your Digital Ocean account.

After you’ve done that, I can get a list of your keys by executing this in your project directory:

1

$ knife digital_ocean sshkey list

To get a sense of what your options are, you can use Knife to run of list of what Digital Ocean offers. There are various OS options, image sizes, and hosting locations. You can see what’s available using some of these command:

1
2
3
4

$  knife digital_ocean region list # list hosting regions
$  knife digital_ocean size list  # list image sizes 
$  knife digital_ocean image list # list your images 
$  knife digital_ocean image list --global # list all the images

You can see the whole list of commands at https://github.com/rmoriz/knife-digital_ocean.

So let’s finally make our damn server already. I can do that with this command:

1
2

$ knife digital_ocean droplet create --server-name catalog-dev.wmu.se --image 2676 \
    --size 63 --location 2 --ssh-keys 11701

If you read about that page with list of commands, you’ve probably guessed that this creates a single core 1GB 30GB server, running Ubuntu 12.04 server in Amsterdam with my account’s SSH keys preloaded.

After you run the create command, you’ll be given a IP address (which you can use to setup your DNS) and get an email with your root password.

Now before I do anything else, log into the root account and change the password or better yet just turn off password authentication for ssh access.

Chef Up

First we need to make our cookbook:

1

$ knife cookbook create -o ./site-cookbooks catalog

This will scaffold out a file directory called ./site-cookbooks that we will use add our own recipes. But one of the great things about Chef is that there’s lot of recipes you can find out there to do more of the work for you. Take a look at the ./Cheffile

This list out all the third part recipes we’re going to need for this project. If you find a recipe you’d like to use, you can add it here. Also have a look at site-cookbooks/catalog/attributes/default.rb.

I guess now is a good time to go over user creation.

You’re going to want more user accounts than just root, especially since as you see from the attributes/default.rb, we’re going to block off ssh root login. The easiest way to make user account is with data bags. Data bags are just json files of key/value attributes. They are located in the ./data_bags folder of the project’s root directory.

For this project, I am going to make two users : Me and rails. There are located in ./data_bags/users

The rails user will be the user that capistrano logs in to deploy the application. I do not want that user to be privileged. However, I want my user to be all-powerful.

To make the passwords, you can hash them out using mkpasswd -m sha-512 or (for OS X users) (for OS X users) echo -n “a password” | openssl dgst -sha512. You can also add in your public ssh key here and your dot files if you’re using Homesick (you should). The users that are to be created are added to the default.users array in the attributes/default.rb file.

But what about all those other “accounts” I need to set up? My MySQL root user, my email SMTP account, blah blah blah. For this we’re going to want to use encrypted databags. However, chef solo seems to have some issues with these, so we’re going to need a little help.

Take a look at this guy’s gist , which will give you a way to edit encrypted data bags using Chef solo. I copied that gist in directory called “libraries” in the project folder and made a secret key like this:

1
2

$ openssl rand -base64 512 > data_bag_key
$ echo data_bag_key >> .gitignore

So, the Percona recipe requires an encrypted data bag to install MySQL, so I make a file called data_bags/passwords/mysql.json that initially just has this:

1
2
3

 {
  "id": "mysql"
}

Now we can add our encrypted passwords like by running this from our project root directory:

1

$  ./libraries/edit_bag.rb passwords mysql

Your text editor should open to edit your mysql.json. Add “user”: “password” values for users “root”, “backup”, and “replication”. When you save the file, the script will encrypt your databag for you.

Boosh.

It’s a little akward, but it seems like the easiest way to go to encrypted data bags using the new version of Chef Solo.

I do the same for system.json (for mysql’s log rotater), rails.json ( for the app’s database credentials ), and gmail.json (which is what I going to use as a dinky email relay) and newrelic.json (from system monitoring).

Now that we have most of our default settings and data bags in place, lets move on to setting up our recipes. First I run these commands:

1
2

$ librarian-chef install # this is like a bundle install
$ knife solo bootstrap root@catalog-dev.wmu.se

The first command will install all your third-party cookbooks to the cookbooks directory, just like a bundle install.

The second command will install a json file in the node directory. This json file sets what recipes you want to run (in the aptly named “run_list” value) as well as any node-specific attributes you want to define. Here you can add or remove any recipes you want from the list.

For this project, I’m running two main recipes, “requirements” and “default”.

Have a look at site-cookbooks/recipes/requirements.rb.

Now look at the default recipe:

At the end of this recipe, I run two more site-cookbook recipes :catalog::solr-config and catalog::rails_application.

First site-cookbooks/recipes/solr-config.rb :

and site-cookbooks/recipes/rails_application (I have not idea why I went underscore on that one):

I’d recommend taking a hard look at the nginx.erb template. For this appication, I’m keeping a non-SSL path open to query Solr, so I can do some AJAX queries that will not require the processor overhead SSL requires. For everything else, it gets pushed to the SSL site. The /solr path also requires some basic auth, which we setup in the solr-config recipe. Of course, you can lock Solr down more if you chose and probably should if you are storing sensitive data.

And with that, we’re pretty much ready to run this thing.

1

$ knife solo bootstrap catalog-dev.wmu.se

You should see all the recipes run and you can see if the web server and jetty is running by going to you host.

In the next post I’ll go over how to deploy you rails application with Capistrano.