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.
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.
$ 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.
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.
$ 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
And, voilà! Here's a list of Wagon's commands and what they do. Let's try another command,
$ wagon version 1.5.1
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 RubyGems.org. If you don't have the latest version, you might want to upgrade your gems using
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?
$ wagon help init Usage: wagon init NAME [PATH] Options: -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
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.
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.
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 open http://0.0.0.0:3333
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.
$ cd wisdom_for_wanders
bundle install, which will install Wagon's gem dependencies.
$ bundle install Fetching gem metadata from https://rubygems.org/........ Fetching gem metadata from https://rubygems.org/.. 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 (184.108.40.206) Using listen (0.7.3) Using locomotivecms-liquid (2.6.0) Using locomotivecms-solid (0.2.2.1) 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 `bundle show [gemname]` to see where a bundled gem is installed.
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.
$ bundle exec wagon serve >> Thin web server (v1.5.1 codename Straight Razor) >> Maximum connections set to 1024 >> Listening on 0.0.0.0:3333, CTRL+C to stop
bundle exec business?
Here's the short version: bundler is a tool that lets us keep gem dependencies for different projects separate. The
bundle install 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
bundle exec before all Wagon commands. Actually, it's not required for all 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.
http://0.0.0.0:3333 in a web browser. It should look like the screenshot below, since we're just using the standard Bootstrap 3 template.
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.
wisdom_for_wanderers ├── Gemfile ├── Gemfile.lock
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!
├── app │ ├── content_types │ └── views │ ├── pages │ │ ├── 404.liquid │ │ └── index.liquid │ └── snippets │ └── footer.liquid
app folder holds several directories that make up the core of your site.
content_types directory is for YAML files that define the structure of content types.
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.
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,
├── config │ ├── deploy.yml │ ├── site.yml │ └── translations.yml
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.
config.ru is used by Wagon web server. You'll never need to change or worry about this one either, hurray!
data directory is for YAML files defining content entries for the site's content types.
├── log │ └── wagon.log
wagon.log file contains error messages which can useful when debugging.
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 Initialized empty Git repository in /Users/me/source/wisdom_for_wanderers/.git/
Next, create a
.gitignore file in the project directory and fill it in with the following contents.
/.bundle /config/deploy.yml /log
The files listed will be ignored by git and never saved to our repository. The
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.
Add all of the files in this directory to the repo using
git add and commit everything.
$ git add . $ git commit -m "initial commit"
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.Next: configuring the site