Locomotive est un CMS (Content Management System) fait avec Ruby on Rails qui rencontre un certain succès auprès des créateurs de sites web professionnels.

Ce tutoriel explique comment configurer et utiliser votre instance Simple Hosting pour servir de Engine, dans lequel vous pourrez construire et déployer un ou plusieurs sites (ou Wagons).

La documentation fournie par les créateurs de Locomotive CMS est très complète, et nous vous recommandons de la consulter pour mieux comprendre les concepts de Engine (moteur/conteneur de sites ou projets) et Wagon (site ou projet) .

Suivez les instructions fournies par LocomotiveCMS pour installer les dépendances nécessaires à son fonctionnement, puis assurez-vous que vous disposez des outils requis pour déployer votre code avec Git.

En tout, vous avez besoin des logiciels suivants pour faire fonctionner l'outil localement:

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

Une fois ces dépendances assurées, vous pouvez installer la gem Wagon

$ gem install locomotivecms_wagon

Pour générer le Engine local, commencez par créer une application Rails avec quelques options

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

Dans le Gemfile, assurez-vous de préciser la version de Rails suivante pour éviter des erreurs de gestion dépendances; cela installera la version de 3.2.X de Rails la plus récente quand-même:

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

Maintenant vous pouvez installer les dépendances avec Bundle.

$ bundle install

Avec cela, l'application Ruby on Rails de base est prête. Maintenant nous allons y installer l'Engine de LocomotiveCMS, nous servant de son générateur.

$ bundle exec rails generate locomotive:install

À sa conclusion, ce script d'installation vous proposera d'éditer quelques fichiers, dont le fichier de configuration de votre Engine, où vous pouvez notamment préciser si votre installation est single- ou multi-sites, les addresses email par défaut, etc.

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

# Modifiez ce fichier selon vos besoins

Il est très important de modifier le fichier Carrierwave pour faire fonctionner l'upload de fichiers avec votre instance Simple Hosting. Vous pouvez copier-coller le bout de code suivant et remplacer les contenus par défault.

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

Ensuite, ajoutez cette ligne au fichier .gitignore si vous voulez ignorer et ne pas synchroniser les fichiers uploadés

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

La prochaine étape est de configurer `config/mongoid.yml` pour se servir de MongoDB, tant localement que sur Simple Hosting:

—
file: config/mongoid.yml
---

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

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

production:
  sessions:
    default:
      database: mon_cms_production
      hosts:
        - localhost:27017
  options:
    identity_map_enabled: true

Et voilà, avec ça votre installation est prête pour courir localement et pour être déployée sur votre instance Simple Hosting. Pour la lancer localement, il suffit d’exécuter la commande suivante:

$ bundle exec unicorn_rails 

Suivez les instructions qui suivent pour déployer et faire fonctionner votre Engine sur votre instance Simple Hosting

Commençons par initialiser le répertoire Git et pousser le code sur l’instance:

$ git init 
$ git add .
$ git commit -am 'First install'
$ git remote add gandi git+ssh://<login>@git.dc<dc_id>.gpaas.net/default.git
$ git push gandi master

Puis il faut déployer le code

$ ssh <login>@git.dc<dc_id>.gpaas.net 'deploy default.git'

Finalement, il faut pré-compiler les ressources en accédant à la console SSH et executant la commande suivante:

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

Maintenant vous pouvez pointer votre navigateur à l'URL de votre instance et configurer Locomotive. La section suivante vous montre comment pousser des Wagons sur l'Engine que vous venez d'installer sur votre instance.

http://<votre_instance>/locomotive

Un Wagon est un site qui peut être contenu dans un Engine de LocomotiveCMS. Vous pouvez en créer un en utilisant la commande suivante:

$ wagon init <nom_du_repertoire>

Pour le déployer sur votre instance, vous pouvez simplement configurer le fichier `config/deploy.yml` pour y mettre l'URL de votre instance, et vos identifiants (soit l'email et MDP que vous avez choisi pour Locomotive, ou bien votre clé d'API).

development:
  host: localhost:8080
  api_key: "your api key"
staging:
  host: staging.example.com
  email: john@doe.net
  password: apassword
  # api_key: <your api key here>
production:
  host: "your.instance.url"
  api_key: "your api key"

Pour conclure, utilisez la commande Push en utilisant l'environnement approprié:

$ wagon push production

Si tout est “vert”, vous pouvez accéder à votre site en accédant à l'URL de votre instance.