Install Locomotive Engine
This page will help you get started with Locomotive on your machine (*nix systems).
Locomotive, the Ruby on Rails application, also named Engine, is only dedicated to the creation / editing of content. In other words, we don't allow anymore developers to create a whole site straight from the UI or even edit the template of a page.
So, sites are exclusively coded locally using our open source tool: Wagon.
Installing the Engine
Prerequisites:
- MongoDB 3.4 installed and running on your machine.
- Ruby 2.5 (or higher)
- Ruby on Rails 5.1.6 (or any version below 5.2.0)
- NodeJS
Create a new Ruby on Rails app:
rails new locomotiveapp --skip-bundle --skip-active-record
cd locomotiveapp
Rails 5.2 already installed?
No problem, just run
rails _5.1.6_ new locomotiveapp --skip-bundle --skip-active-record
instead of the command above.
In case you need to force a version of ruby, run the following statement.
echo "2.5.1" > .ruby-version
Make sure you delete the robots.txt file from public/ otherwise any future sites' robots.txt setting won't be picked up.
Add the Mongoid and Devise gems in your Gemfile.
gem 'devise', '~> 4.4.3'
gem 'mongoid', '~> 6.4.0'
Install them and run their setup tasks
bundle install
rails generate mongoid:config
rails generate devise:install
Update the Gemfile of the Rails application by adding the locomotivecms gem.
gem 'locomotivecms', '~> 3.4.0'
In case you are using rbenv:
echo "2.5.1" > .ruby-version
Run the Locomotive installation generator
bundle update
bundle exec rails generate locomotive:install
The installation adds the puma gem to the Rails application's Gemfile. An additional bundle install is required:
bundle install
Finally, run the Rails server
bundle exec rails server
Now, open your browser at http://localhost:3000/locomotive. You should see the Locomotive Sign in page.
Creating your first account and site
Click on "Do not have an account?" link at the bottom page and fill in the Sign up form in order to create your first account.
On the next screen, click on the "Add a new site" button.
Fill in the form and press "Create site"
Pushing a site template with Wagon
Prerequisites:
- site handle you assigned to your site when you created it (radioactive-fern-4299 from the screenshot in the previous chapter).
- the email you used to sign up
- your API key that you can find at this url: http://localhost:3000/locomotive/my_account/edit#api
If you have not installed Wagon, do:
curl -O https://wagonapp.s3.amazonaws.com/myportfolio.zip
unzip myportfolio.zip
cd My\ portfolio/
bundle install
Upgrading Wagon
You can upgrade it by running bundle upgrade at the root folder of your Wagon site.
Otherwise, if you have followed on the quick start page, go to the folder where you created your portfolio app.
If you have not followed the tutorial on the quick start page, do:
mkdir -p ~/Sites/Wagon
cd ~/Sites/Wagon
wagon init MyPortfolio -t bootstrap
cd MyPortfolio
bundle install
In all three cases, uncomment / complete the config/deploy.yml file.
local:
host: localhost:3000
handle: <the handle property of your site>
email: <your email>
api_key: <your API key>
Push your site to the Engine
bundle exec wagon push local -d -v
Finally, go back to your site, you should see something similar to the screenshot below.
A quick note on the options you can pass to
bundle exec wagon push local
- -d allows you to deploy data that you may have added (i) to .yml files under the data folder of your site on the Wagon or (ii) in the header of your file, under the editable_elements section;
- -v means verbose and allows you to see what is going when deploying;
- -r allows you to deploy only certain specific resources of your site. The available resource types are: theme_assets, snippets, content_types and pages. You can learn more about these ressources in the section entitled template.
These parameters are also available when deploying to Heroku or on the Station.
Updated over 5 years ago