Welcome to the first episode in a series of short screencasts for the Ruby neo4j gem.  Each episode will describe a different aspect of the gem.  In this first episode, we will start by discussing how to set up a new Ruby on Rails app using Neo4j.  The neo4j gem is not Rails specific so you can use other frameworks like Sinatra or Lotus, but because of the popularity of Ruby on Rails we will be using it for this screencast series.

In this series we're going to create an application to host digital assets which we'll call "asset_portal".  To create your Rails app you can run a `rails new` command as usual.  To use Neo4j instead of ActiveRecord you can give arguments which will set up a new Rails app using Neo4j models.

  rails new asset_portal -m http://neo4jrb.io/neo4j/neo4j.rb -O

The dash-m argument runs a script from the neo4j gem project and the dash-capital-O argument says to exclude ActiveRecord.  There aren't any restrictions on using Neo4j with other ORMs like ActiveRecord, but you will need to configure your app manually to use both.

Once we have our app we need to configure it to connect to our Neo4j server.  We can have it connect to a server that we've already set up, or we can use the gem's built-in `neo4j:install` rake task to download and install a new Neo4j server instance.  You can specify a version or specify that you want the latest version of Neo4j.

  rake neo4j:install[community-latest, development]

Once we have the server installed we can optionally configure it's port using the `neo4j:config` task to something other than the default of 7474:

  rake neo4j:config[development,7000]

Finally to start the server we can run the `neo4j:start` task:

  rake neo4j:start[development]

We can see that this is a normal installation of Neo4j by visiting the web console in our browser.

Once we have a Neo4j server up and running we need to configure Rails to tell it how to connect to the server.  We can do this by adding the following configuration options to our `config/development.rb` file:

  config.neo4j.session_type = :server_db
  config.neo4j.session_path = 'http://localhost:7000'

It's important to note that if you generate a server with the rake task then the default Neo4j authentication will be disabled.  See the gem documentation to configure authentication.

With this in place we can now generate a model.  The neo4j gem is compatible with Rails' model generators

  $ rails g model Asset title:string created_at:datetime updated_at:datetime
      invoke  neo4j
      create    app/models/asset.rb
      invoke    test_unit
      create      test/models/asset_test.rb
      create      test/fixtures/assets.yml

You can see that this creates a model file and the default unit test files just like you would get for ActiveRecord.  However, since Neo4j is schemaless, properties are declared in the model rather than defining migrations to create a table.

In the console we see that we can use this model to create and query nodes in our Neo4j database.

  Asset.create(title: 'A predictive analysis of predictive analytics')

  Asset.first

In the console we can see the Cypher queries which are being executed.  When running a server we also see these in the development log.

Once we have configured our Rails app we can generate controllers and views as we normally would to present our data to users.

  $ rails g controller assets

To have a minimal webpage displaying data from Neo4j we create a controller...

  # app/controllers/assets_controller.rb

  class AssetsController < ApplicationController
    def index
      @assets = Asset.all
    end
  end

A view...

  # app/views/assets/index.html.erb

  <% @assets.each do |asset| %>
    <%= asset.title %>
  <% end %>

And a route...

  # config/routes.rb

  Rails.application.routes.draw do
    root 'assets#index'
  end

Then we start up our server and see the result!

That's all for this introductory episode.  Future episodes will be dedicated to topics such as properties, associations, query building, relationship modeling, and more...  If you have questions check out the project's README for ways to reach out to the neo4j gem team.  Happy graphing!
