Fetching contributors…
Cannot retrieve contributors at this time
319 lines (248 sloc) 16.3 KB
title: 1.1 Create the Wagon site
listed: true
position: 1
{% extends 'index' %}
{% block 'content' %}
The first step to making our blog will be to create a new site with Wagon. But, let's hold off on that for a moment and briefly explore the `wagon` command line utility.
<div class="alert alert-info">
As per the prerequisites, you need to have already <a href="/get-started/install-wagon">installed Wagon</a>.
## The help command
Since I would like to make my blog's design responsive, and I'm generally not so good with designing anyway, I plan on using [Twitter Bootstrap]( to help out on the frontend side of things. Fortunately, Wagon comes with some built-in templates for Twitter Bootstrap. We can view Wagon's available templates by using the `wagon list_templates` command.
<pre><span>$ wagon list_templates
blank - A blank LocomotiveCMS site with the minimal files.
bootstrap2 - A LocomotiveCMS site with Twitter Bootstrap (v2.3.2) and Font Awesome (v3.2.1).
bootstrap3 - A LocomotiveCMS site powered by Twitter bootstrap (v3.0.0).
foundation - A LocomotiveCMS site powered by Foundation (v4.3.2).
unzip - Unzip a local or remote (http, https, ftp) zipped LocomotiveCMS site.</span></pre>
As you can see, Wagon comes with several built-in templates, including ones for Bootstrap 2 and Bootstrap 3. Great!
`wagon list_templates` is a handy command and Wagon comes with quite a few more commands, but you don't need to memorize all of them if you can remember just this one: `wagon help`. Let's run that one.
<pre><span>$ wagon help
wagon clone NAME HOST [PATH] # Clone a remote LocomotiveCMS site
wagon destroy ENV [PATH] # Destroy a remote LocomotiveCMS engine
wagon generate TYPE ...ARGS # Generate resources (content_types, page, snippets) for a LocomotiveCMS site
wagon help [COMMAND] # Describe available commands or one specific command
wagon init NAME [PATH] # Create a brand new LocomotiveCMS site
wagon list_templates # List all the templates to create either a site or a content type
wagon pull ENV [PATH] # Pull a site from a remote LocomotiveCMS engine
wagon push ENV [PATH] # Push a site to a remote LocomotiveCMS engine
wagon serve [PATH] # Serve a LocomotiveCMS site from the file system
wagon version # Version of the LocomotiveCMS wagon</span></pre>
And, voilà! Here's a list of Wagon's commands and what they do. Let's try another command, `wagon version`.
<pre><span>$ wagon version
As advertised, this prints out what version of Wagon you have. At the time of writing, the latest version of Wagon was 1.5.1, but you can [check for the current latest version on]( If you don't have the latest version, you might want to upgrade your gems using `gem update`.
## Creating a new Wagon project
Let's create a new Wagon site for your project. According to `wagon help`, running `wagon init` creates a new site, but how do we use the Bootstrap template?
<pre><span>$ wagon help init
wagon init NAME [PATH]
-t, [--template=TEMPLATE] # instead of building from a blank site, you can have a pre-fetched site with form a template (see the templates command)
# Default: blank
-v, [--verbose] # display the full error stack trace if an error occurs
Create a brand new LocomotiveCMS site</span></pre>
Question answered. As `wagon help init` points outs, we need to use the `--template` option to specify a template. I won't need IE 6 or 7 support, so I'm going to go with Bootstrap 3.
Also, we need a name for the site. This is a travel blog, so I'm going to name it _Wisdom for Wanderers_. However, for the wagon command I will use an underscored version of this, `wisdom_for_wanderers`. We could have a spaced name (if we were careful to quote it when running the command), but I don't like spaces in my folder names.
Let's run the `wagon init` command.
<pre><span>$ wagon init wisdom_for_wanderers --template=bootstrap3
create wisdom_for_wanderers
create wisdom_for_wanderers/Gemfile
create wisdom_for_wanderers/app/content_types
create wisdom_for_wanderers/app/views/pages/404.liquid
create wisdom_for_wanderers/app/views/pages/404.liquid.haml
create wisdom_for_wanderers/app/views/pages/index.liquid
create wisdom_for_wanderers/app/views/pages/index.liquid.haml
create wisdom_for_wanderers/app/views/snippets/footer.liquid
create wisdom_for_wanderers/app/views/snippets/footer.liquid.haml
create wisdom_for_wanderers/
create wisdom_for_wanderers/config/deploy.yml
create wisdom_for_wanderers/config/site.yml
create wisdom_for_wanderers/config/translations.yml
create wisdom_for_wanderers/data
create wisdom_for_wanderers/public/fonts/glyphicons-halflings-regular.eot
create wisdom_for_wanderers/public/fonts/glyphicons-halflings-regular.svg
create wisdom_for_wanderers/public/fonts/glyphicons-halflings-regular.ttf
create wisdom_for_wanderers/public/fonts/glyphicons-halflings-regular.woff
create wisdom_for_wanderers/public/javascripts/bootstrap.js
create wisdom_for_wanderers/public/javascripts/bootstrap.min.js
create wisdom_for_wanderers/public/samples/apple-touch-icon-114-precomposed.png
create wisdom_for_wanderers/public/samples/apple-touch-icon-144-precomposed.png
create wisdom_for_wanderers/public/samples/apple-touch-icon-57-precomposed.png
create wisdom_for_wanderers/public/samples/apple-touch-icon-72-precomposed.png
create wisdom_for_wanderers/public/samples/favicon.png
create wisdom_for_wanderers/public/stylesheets/bootstrap-theme.css
create wisdom_for_wanderers/public/stylesheets/bootstrap-theme.min.css
create wisdom_for_wanderers/public/stylesheets/bootstrap.css
create wisdom_for_wanderers/public/stylesheets/bootstrap.min.css
Do you prefer HAML templates ?</span></pre>
The commanded prints out each file it creates and then asks whether you would like to use [HAML Templates]( I tend to think stuff like HAML is pretty cool, but to make this tutorial as accessible as possible I'm going to use HTML templates. Those following along at home whom would like to use HAML can do so by typing _yes_. Everyone else, let's type _no_ and continue.
<pre><span>Do you prefer HAML templates ? no
remove wisdom_for_wanderers/app/views/pages/index.liquid.haml
remove wisdom_for_wanderers/app/views/pages/404.liquid.haml
remove wisdom_for_wanderers/app/views/snippets/footer.liquid.haml
Congratulations, your site "wisdom_for_wanderers" has been created successfully !
Next steps:
cd ./wisdom_for_wanderers
bundle install
bundle exec wagon serve
The wagon command prints a congratulatory message to indicate that our site was successfully created. It also provides the next steps. Start by changing into the newly created project directory.
<pre><span>$ cd wisdom_for_wanders</span></pre>
Then run `bundle install`, which will install Wagon's gem dependencies.
<pre><span>$ bundle install
Fetching gem metadata from
Fetching gem metadata from
Resolving dependencies...
Using RedCloth (4.2.9)
Using i18n (0.6.5)
Using multi_json (1.2.0)
Using activesupport (3.2.15)
Using coderay (1.1.0)
Using erubis (2.7.0)
Using better_errors (1.0.1)
Using chronic (0.9.1)
Using chunky_png (1.2.9)
Using coffee-script-source (1.6.3)
Using execjs (2.0.2)
Using coffee-script (2.2.0)
Using colorize (0.5.8)
Using commonjs (0.2.7)
Using fssm (0.2.10)
Using sass (3.2.12)
Using compass (0.12.2)
Using daemons (1.1.9)
Using rack (1.5.2)
Using dragonfly (0.9.15)
Using eventmachine (1.0.3)
Using faker (0.9.5)
Installing ffi (1.9.3)
Using tilt (1.3.3)
Using haml (4.0.3)
Using hike (1.2.3)
Using json (1.8.1)
Using multi_xml (0.5.5)
Using httparty (0.12.0)
Using multipart-post (1.2.0)
Using httmultiparty (0.3.10)
Using less (2.2.2)
Using libv8 (
Using listen (0.7.3)
Using locomotivecms-liquid (2.6.0)
Using locomotivecms-solid (
Using logger (1.2.8)
Using mime-types (1.25)
Using sprockets (2.10.0)
Using sprockets-sass (1.0.2)
Using stringex (1.4.0)
Using tzinfo (1.0.1)
Using zip (2.0.2)
Using locomotivecms_mounter (1.3.1)
Using rack-cache (1.2)
Using redcarpet (3.0.0)
Using thin (1.5.1)
Using thor (0.18.1)
Using will_paginate (3.0.5)
Using locomotivecms_wagon (1.3.1)
Using rb-fsevent (0.9.3)
Using rb-inotify (0.9.2)
Using ref (1.0.5)
Using therubyracer (0.12.0)
Using wdm (0.1.0)
Using bundler (1.3.5)
Your bundle is complete!
Use &#96;bundle show [gemname]&#96; to see where a bundled gem is installed.</span></pre>
The `bundle install` command is very informative and it prints out the name of every ruby gem it installs. Let's test that everything is working by running Wagon's built-in web server. Use the `bundle exec wagon serve` command to start the server.
<pre><span>$ bundle exec wagon serve
&gt;&gt; Thin web server (v1.5.1 codename Straight Razor)
&gt;&gt; Maximum connections set to 1024
&gt;&gt; Listening on, CTRL+C to stop</span></pre>
<div class="alert alert-info">
<p>What's this <code>bundle exec</code> business?</p>
Here's the short version: <a href="">bundler</a> is a tool that lets us keep gem dependencies for different projects separate. The <code>bundle install</code> command doesn't install those gems globally. It installs them just for this project. That way if for some reason later you have a different ruby project that requires different versions of the same gems, each project has its own versions.
So, to make sure that we are running this project's version of a gem, we must put <code>bundle exec</code> before all Wagon commands. Actually, it's not required for <em>all</em> commands, but it's just simpler to always add it.
The command line is now unresponsive. That's because the web server is running in this shell. We can't run any commands in this shell so long as the web server is running. You can quit the web server at any time by pressing `ctrl + c`. For now, leave it running.
Open `` in a web browser. It should look like the screenshot below, since we're just using the standard Bootstrap 3 template.
<img src="{{ 'guides/making-blog/1.1/default_home_page.png' | theme_image_url | resize: '699x>' }}" alt="The Bootstrap 3 template's default home page" />
Success! Our newly created site is working just dandy.
## Exploring the project directory
We've hardly done any work yet, but there sure are a lot of files and directories in our site's project folder. As we develop our blog, we will more learn more about these files and directories, but let's make a quick overview so this mess of files is less intimidating. If something doesn't make sense, don't worry: we'll be coming back to the important stuff later.
├── Gemfile
├── Gemfile.lock</span></pre>
`Gemfile` is used by bundler to determine what Ruby gems are needed for this project. `Gemfile.lock` is created when you run `bundle install` to note which exact versions of each gem have been installed. You'll never need to change or worry about either file, hurray!
<pre><span>├── app
│   ├── content_types
│   └── views
│   ├── pages
│   │   ├── 404.liquid
│   │   └── index.liquid
│   └── snippets
│   └── footer.liquid</span></pre>
The `app` folder holds several directories that make up the core of your site.
The `content_types` directory is for YAML files that define the structure of content types.
The `app/views/pages` directory is for liquid templates representing the site's pages. The Bootstrap template we used preloaded the site with an index page and a 404 page.
The `app/views/snippets` folder holds liquid markup files for reuse in templates. In other frameworks these are sometimes called _partials_. The Bootstrap template preloaded the site with a footer snippet, `footer.liquid`.
<pre><span>├── config
│   ├── deploy.yml
│   ├── site.yml
│   └── translations.yml</span></pre>
The `config` directly holds various configuration files. `deploy.yml` sets the connection details for LocomotiveCMS Engines we can deploy this site to. `site.yml` sets some general settings for the site. `translations.yml` defines localization strings.
`` is used by Wagon web server. You'll never need to change or worry about this one either, hurray!
<pre><span>├── data</span></pre>
The `data` directory is for YAML files defining content entries for the site's content types.
<pre><span>├── log
│   └── wagon.log</span></pre>
The `wagon.log` file contains error messages which can useful when debugging.
<pre><span>└── public
├── fonts
│   ├── glyphicons-halflings-regular.eot
│   ├── glyphicons-halflings-regular.svg
│   ├── glyphicons-halflings-regular.ttf
│   └── glyphicons-halflings-regular.woff
├── javascripts
│   ├── bootstrap.js
│   └── bootstrap.min.js
├── samples
│   ├── apple-touch-icon-114x114-precomposed.png
│   ├── apple-touch-icon-144x144-precomposed.png
│   ├── apple-touch-icon-72x72-precomposed.png
│   ├── apple-touch-icon-precomposed.png
│   ├── favicon.png
│   └── pages
└── stylesheets
├── bootstrap-theme.css
├── bootstrap-theme.min.css
├── bootstrap.css
└── bootstrap.min.css</span></pre>
The `public` directory holds all of our site's assets: fonts, javascripts, images, and stylesheets. The `public/samples` directory is for images. That name probablys seems unintuitive now, but it will make more sense later. As you can see, the Bootstrap template has preloaded the site with some various stylesheets, javascripts, images, and fonts.
Hopefully, the project directory is now a little less opaque.
## Setting up git
A final and optional step to creating our Wagon site is to setup some kind of source versioning system. This tutorial is going to use [git](, because it's the versioning system de jour. You are of course welcome to use [Subversion](, [Mecurial](, or any other system you like.
If you don't have previous experience with a source control system, you can skip this step. If you're interesting in learning about source versioning, I would encourage you to [checkout git]( (excuse the pun).
Open a command line, navigate to the project directory, and run `git init`.
<pre><span>$ git init
Initialized empty Git repository in /Users/me/source/wisdom_for_wanderers/.git/</span></pre>
Next, create a `.gitignore` file in the project directory and fill it in with the following contents.
The files listed will be ignored by git and never saved to our repository. The `.bundle` and `log` directories just contain logs that shouldn't be in the source repository. And `deploy.yml` will enventually contain passwords or API keys, so it's important we never accidentally commit that kind of sensitive information.
<div class="alert alert-info">Tip for git beginners: Mac users should Google how to create a global git ignore file and add <code>.DS_STORE</code> to it.</div>
Add all of the files in this directory to the repo using `git add` and commit everything.
<pre><span>$ git add .
$ git commit -m "initial commit"</span></pre>
Done! We've successfully created a new Wagon site. So far it's just a dummy site, but it's created and we've setup git, so we're ready to start developing.{href: "/making-blog/1-2-configure-site"} Next: configuring the site
{% endblock %}