====== Locomotive CMS on Simple Hosting =======

[[http://locomotivecms.com|Locomotive]] is a Content Management System (CMS) written in Ruby on Rails that has become a popular choice by professional web designers.

This tutorial describes how to configure and use Simple Hosting to serve Engine, in which you can build and deploy one or more sites (or Wagons).

<note important>Locomotive CMS therefore requires a Ruby + MongoDB instance of size M or above. </note>



<note tip>The Locomotive CMS documentation is quite comprehensive, and we highly recommend checking it out in order to better understand the concepts of Engine (motor/container of sites or projects) and Wagon (site or project). [[http://doc.locomotivecms.com/get-started|Official Locomotive CMS documentation]]</note>

====== Installation on your local machine =======

Follow the instructions provided by Locomotive CMS to install the dependencies it requires, then check that you have the required tools to deploy your code with git.

In all, you will need the following tools installed locally:

  * Git
  * MongoDB
  * ImageMagick
  * Ruby 1.9.3
  * Bundler et Rake
  * Rails ~> 3.2.16

Once these dependencies have been installed, you can install the Wagon gem:

<code>
$ gem install locomotivecms_wagon
</code>

To generate the local Engine, start by creating a Rails application with a few options:
<code>
$ rails new example_cms --skip-active-record --skip-test-unit --skip-javascript --skip-bundle 
</code>

In the Gemfile, make sure to specify the following version of Rails in order to avoid dependency management errors. This will install the most recent version of Rails 3.2.X:

<code>
---
file: Gemfile
---
source 'https://rubygems.org'

gem 'rails', '~>3.2.16'

gem 'locomotive_cms', '~> 2.4.1', :require => 'locomotive/engine'

gem 'execjs'
gem 'therubyracer', :platforms => :ruby

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'compass-rails',  '~> 1.1.3'
  gem 'sass-rails',   '~> 3.2.3'
  gem 'coffee-rails', '~> 3.2.1'
  gem 'uglifier', '>= 1.0.3'
end

# Use unicorn as the app server
gem 'unicorn'

</code>

Now you can install dependencies with Bundle:

<code>

$ bundle install

</code>

With that, Ruby on Rails is ready. Now we'll install Locomotive CMS Engine using its generator:

<code>

$ bundle exec rails generate locomotive:install

</code>


====== Simple Hosting configuration =======

At its conclusion, the install script will prompt you to modify a few files, including the configuration file of your Engine, where you can notably specify whether you want a single- or multi-site installation, default email addresses, and so on.

<code>

---
file: config/initializers/locomotive.rb
---

# Modify this file according to your needs

</code>

It's very important to modify the ''Carrierwave'' file in order for the file upload function to work with your Simple Hosting instance. You can copy and paste the code snippet below, replacing the default contents:

<code>

---
file: config/initializers/carrierwave.rb
---

CarrierWave.configure do |config|

  config.cache_dir = File.join(Rails.root, 'tmp', 'uploads')

  config.storage = :file
  config.root = File.join(Rails.root, 'public', 'uploads')

end

</code>

Next, add this line to your ''.gitignore'' file if you do not want to syncronize the uploaded files:

<code>
---
file: .gitignore
—
[...]
public/uploads
[…]
</code>

The next step is to configure ''config/mongoid.yml'' to use MongoDB, locally as well as on your Simple Hosting instance:

<code>
—
file: config/mongoid.yml
---

development:
  sessions:
    default:
      database: my_development_cms
      hosts:
        - localhost:27017
  options:
    identity_map_enabled: true

test:
  sessions:
    default:
      database: my_preprod_cms
      hosts:
        - localhost:27017
  options:
    identity_map_enabled: true

production:
  sessions:
    default:
      database: my_production_cms
      hosts:
        - localhost:27017
  options:
    identity_map_enabled: true
</code>

Voilà, with that your installation is ready to be run locally and to be deployed on your Simple Hosting instance. To launch it locally, run the following command:

<code>
$ bundle exec unicorn_rails 
</code>

Follow these instructions to deploy and launch your Engine on your Simple Hosting instance:

====== Deployment on Simple Hosting =======
Let's start by initializing a git repository and push your code to your instance (replacing LOGIN and DC_ID as appropriate):

<code>
$ git init 
$ git add .
$ git commit -am 'Initial install'
$ git remote add gandi git+ssh://LOGIN@git.DC_ID.gpaas.net/default.git
$ git push gandi master
</code>

Then, deploy the code with this command:

<code>
$ ssh LOGIN@git.DC_ID.gpaas.net 'deploy default.git'
</code>
Finally, pre-compile the resources by accessing the SSH console and running the following command:

<code>
$ cd web/vhosts/default/
$ bundle exec rake assets:precompile
</code>

Now you can point your web browser to the URL of your instance and configure Locomotive. The following section will show you how to push Wagons on the Engine you have just installed on your instance.

<code>
http://<your_instance_URL>/locomotive
</code>

====== Pushing a Wagon ======

A Wagon is a site which can be contained in a Locomotive CMS Engine. You can create one by running the following command, replacing ''DIRECTORY_NAME'' as appropriate:

<code>
$ wagon init DIRECTORY_NAME
</code>

To deploy it on your instance, you can simply add the URL of your instance to the ''config/deploy.yml'' file, as well as your credentials (either the email and password you chose for Locomotive, or your API key).

<code>
development:
  host: localhost:8080
  api_key: "YOUR_API_KEY"
staging:
  host: staging.example.com
  email: jeana@example.net
  password: apassword
  # api_key: "YOUR_API_KEY"
production:
  host: www.example.com
  api_key: "YOUR_API_KEY"
</code>

Finally, use the ''Push'' command and specify the appropriate environment:

<code>
$ wagon push production
</code>

If everything is in order, you should be able to access your site at the URL or domain name attached to your instance!