Rails / MongoDB
===============

.. include:: beta.rst

This quickstart will go through the steps of:

* Creating a `Rails <http://guides.rubyonrails.org/getting_started.html>`_ bookmarking app
* Connecting it to `mLab MongoDB <https://mlab.com/>`_, a leading database-as-a-service provider
* Deploying the app on the drie push platform

.. note:: Please fulfill these prerequisites before doing this quickstart.

  #. `Rails <http://guides.rubyonrails.org/getting_started.html>`_ installed on your local machine. This example uses Rails 4.
  #. `mLab MongoDB account <https://mlab.com/>`_ 
  #. `mLab MongoDB database <http://docs.mlab.com/>`_ 
  #. `mLab MongoDB database user <http://docs.mlab.com/connecting/#users>`_ authorised to use the database above


1. Create a new Rails app
-------------------------

We will be creating an app that stores your favourite bookmarks. Let's create a project called ``drie-bookmarker``::

    $ rails new drie-bookmarker --skip-active-record
    $ cd drie-bookmarker

Please take notice of the ``--skip-active-record`` flag. We need to do this for Rails apps that will be deployed to drie push, because if we don't do this, the app generated by ``rails new`` will insert the sqlite3 gem, which is not allowed by the `Ruby buildpack <https://github.com/heroku/heroku-buildpack-ruby.git>`_.

2. Add the mongoid MongoDB driver to the Rails app
--------------------------------------------------

The `mongoid MongoDB driver <https://docs.mongodb.com/ruby-driver/master/tutorials/5.1.0/mongoid-installation/>`_ driver is the official MongoDB `Object Document Mapper <https://docs.mongodb.com/ruby-driver/master/>`_ for Ruby apps::

    $ vi Gemfile

Open Gemfile in your favourite editor and add these lines at the end of the file to add the mongoid MongoDB driver to your Rails app::

    # Mongo DB driver for rails
    gem "mongoid", '~> 5.1.0'
    gem "bson_ext"

Once you make the Gemfile change, install the changes into your Rails app::

    $ bundle install

3. Create mongoid.yml config file
---------------------------------

Run this command to generate the mongoid config file::

    $ rails g mongoid:config
    $ vi config/mongoid.yml

This creates the config file located at config/mongoid.yml.

We need to modify mongoid.yml to connect to our mLab MongoDB database. Please delete all the lines from mongoid.yml and replace it with these lines::

    production:
      clients:
        default:
          uri: <%= ENV['MONGODB_URI'] %>

This is a very basic config to connect to mLab's MongoDB.

.. warning::

    The free tier of mLab does not provide TLS encryption. For production use, we strongly advise using a mLab tier with TLS to secure your database traffic between drie and mLab.

For in-depth connection settings regarding mLab and mongoid, please check out these links:

* `mLab documentation <http://docs.mlab.com/>`_
* `mLab SSL DB connection <http://docs.mlab.com/ssl-db-connections/>`_
* `Mongoid documentation <https://docs.mongodb.com/ruby-driver/master/mongoid-tutorials-5.1/>`_

The last line enables us to load the ``MONGODB_URI`` from environment variables. We will set that later.

4. Create your bookmark model
-----------------------------

We will cheat a bit and generate the bookmark model with Rails scaffold::

    $ rails g scaffold bookmark name:string url:string

5. Create a local git repo and set it up to deploy to drie push
---------------------------------------------------------------

::

    $ git init
    $ git add *
    $ git commit -m "Created drie bookmarker app and setting up to deploy to drie."

After you've created your local git repo, we now set up the remote drie push git repo where we push our code.::

    $ app_name=$(curl -s http://m.rang.app.push.drieapp.co)   # generates a random app name for you
    $ echo "Your app is called ${app_name}"               # you can see what app name was generated for you
    $ git remote add drie ${app_name}.app@push.drieapp.co:code.git


6. Deploy you code to drie push
-------------------------------

::

    $ git push --set-upstream drie master

This pushes up your code to drie push where it builds on the remote server.

7. Set the MONGODB_URI environment variable in drie push
--------------------------------------------------------

You will need to get the MongoDB URI from `mLab <https://mlab.com/>`_. Log into your mLab account and go to:
``https://mlab.com/databases/<your-database-name>``

You can see the ``dbuser`` and ``dbpassword`` that you set up against your database here: ``https://mlab.com/databases/<your-database-name>#users``

The MongoDB URI pattern should be 
``mongodb://<dbuser>:<dbpassword>@<someserver>.mlab.com:<portnum>/<your-database-name>``

To set the ``MONGODB_URI`` environment variable in drie push, run the command below, replacing the placeholders for ``dbuser``, ``dbpassword``, ``someserver``, ``portnum`` and ``your-database-name``::

    $ ssh ${app_name}.app@push.drieapp.co configure environment -s MONGODB_URI=mongodb://dbuser:dbpassword@someserver.mlab.com:portnum/your-database-name

8. Confirm that your bookmarking app works
------------------------------------------

::

    $ curl http://master.${app_name}.app.push.drieapp.co/bookmarks

You should see an empty list where you can add new bookmarks.
Congratulations! You've successfully deployed your Rails / mLab MongoDB app on drie push!