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).

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:

$ gem install locomotivecms_wagon

To generate the local Engine, start by creating a Rails application with a few options:

$ rails new example_cms --skip-active-record --skip-test-unit --skip-javascript --skip-bundle 

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:

---
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'

Now you can install dependencies with Bundle:

$ bundle install

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

$ bundle exec rails generate locomotive:install

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.

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

# Modify this file according to your needs

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:

---
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

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

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

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

—
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

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:

$ bundle exec unicorn_rails 

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

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

$ 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

Then, deploy the code with this command:

$ ssh LOGIN@git.DC_ID.gpaas.net 'deploy default.git'

Finally, pre-compile the resources by accessing the SSH console and running the following command:

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

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.

http://<your_instance_URL>/locomotive

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:

$ wagon init DIRECTORY_NAME

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).

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"

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

$ wagon push production

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