{"__v":1,"_id":"571a587404c2a32b00a1d5e4","api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"body":"Before starting, you need to make sure your system has Ruby 2.1 (or upper) installed. If it is not the case, please follow the **first two steps** of the **[following tutorial](https://gorails.com/setup/osx/10.9-mavericks)**.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Install Wagon\"\n}\n[/block]\nWagon is a command line tool that let's you develop for Locomotive right on your local machine.\n\nWith Wagon, you can generate the scaffolding for a new Locomotive site and start adding the content types and templates you need using any text editor. And thanks to Wagon's built-in web server, you can preview the site with your computer's web browser.\n\nWagon can also deploy sites to any Locomotive Engine using the wagon **deploy** command. Your changes will immediately be reflected on that site without restarting or making any changes to the Engine server app.\n\nTo help you work faster, Wagon comes with support for tools like SASS, HAML, and CoffeeScript. It also works well with source version control systems like git and svn.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"gem install locomotivecms_wagon\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nMake sure it has installed the very last version of Wagon **2.1.0** by typing the following command in your terminal.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"wagon version\",\n      \"language\": \"text\",\n      \"name\": \"Shell\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"\\\"The program 'wagon' is currently not installed\\\" error\",\n  \"body\": \"If you use **rbenv** to manage your ruby installations, you need to run ````rbenv rehash````.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"For advanced users: install it with Devstep and Docker\",\n  \"body\": \"We wrote a guide describing all the steps. It can be found [here](/v3.0/docs/install-wagon-using-devstep-and-docker)\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"The Locomotive.works platform\",\n  \"body\": \"We offer Locomotive site hosting services with a limited free plan. Check out [our site](http://locomotive.works#pricing) for more information.\"\n}\n[/block]\nFor practical reasons, we will use [Locomotive.works](http://locomotive.works) as our deployment target but you're absolutely free to use your own Engine on EC2, Digital Ocean, Engine Yard, Linodes, Heroku or your own server. Don't forget, everything is open source here.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"wagon auth\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nIf you don't have an account, it will create one for you.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Create a new Wagon site\"\n}\n[/block]\nWe start with our built-in Bootstrap site template which embeds the last version of [Bootstrap](http://getbootstrap.com), the popular HTML/CSS framework.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"mkdir -p ~/Sites/Wagon\\ncd ~/Sites/Wagon\\nwagon init MyPortfolio -t bootstrap\\n# Use y or n when questions are promted\\ncd MyPortfolio\\nbundle install\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nNow, let's launch the Wagon preview server.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bundle exec wagon serve \",\n      \"language\": \"shell\",\n      \"name\": \"\"\n    }\n  ]\n}\n[/block]\nOpen your browser at this address **http://localhost:3333/**, you should see a minimal [Bootstrap](http://getbootstrap.com) site.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. Define a content type\"\n}\n[/block]\nOne essential feature of any CMS is the ability to manage structured content. Fortunately, this is one of Locomotive's strongest points.\n\nFor our portfolio site, let's say we want to manage a list of our client projects. Those projects are defined by a name, a client name, a description and an image.\n\n**Wagon** includes a number of built-in generators, \"content_type\" is one of them.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bundle exec wagon generate content_type projects name:string client:string description:text image:file\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nThis command generates 2 files:\n\n- **app/content_types/projects.yml**: It defines the content type.\n- **data/projects.yml**: Auto-generated list of project samples.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"4. Build the page listing the projects\"\n}\n[/block]\n**Liquid** is our powerful templating language. Among a lot of functionalities, it has access to the content types.\n\nFirst, let's generate our page.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bundle exec wagon generate page projects\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nOpen the **app/views/pages/projects.liquid** page in your code editor and replace the liquid code below the second **\"---\"** (line 24) with the following code which lists all the projects in Liquid.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{% extends 'layouts/simple' %}\\n\\n{% block content/main, short_name: true %}\\n\\n{% editable_model projects %}\\n<div class=\\\"row\\\">\\n  <div class=\\\"col-sm-12\\\">\\n    {% for project in contents.projects %}\\n    <div class=\\\"media\\\">\\n      <div class=\\\"media-left\\\">\\n        <img class=\\\"media-object\\\" src=\\\"{{ project.image.url | default: 'http://loremflickr.com/100/100' | resize: '100x100#' }}\\\" alt=\\\"{{ project.name }}\\\">\\n      </div>\\n      <div class=\\\"media-body\\\">\\n        <h4 class=\\\"media-heading\\\">{{ project.name }}</h4>\\n        <p><strong>Client:</strong> {{ project.client }}\\n        <div>\\n          {{ project.description }}\\n        </div>\\n      </div>\\n    </div>\\n    {% endfor %}\\n  </div>\\n</div>\\n{% endeditable_model %}\\n\\n{% endblock %}\",\n      \"language\": \"liquid\"\n    }\n  ]\n}\n[/block]\nIf you refresh your browser, you will notice that a new link (\"Projects\") appeared at the top right corner of the page.\nClick on it and you will see all our samples defined in **data/projects.yml**.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"5. Deploy the site\"\n}\n[/block]\nNow we have a working Wagon site, we want to see it working online, with the backoffice and everything. That's the role of the Locomotive engine.\n\nNow, let's deploy our site!\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bundle exec wagon deploy live\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSince the site doesn't exist yet on the Locomotive engine, you will be asked for a couple of information about it. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"6. Modify the live content of your site!\"\n}\n[/block]\nGo to [locomotive.works](https://station.locomotive.works/_app/sign_in) and sign in with the credentials you entered in the first step.\n\nThen, you will see the following screen:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/m7LYIsEvTWax458jOkNJ_first.png\",\n        \"first.png\",\n        \"2876\",\n        \"1597\",\n        \"#4193d7\",\n        \"\"\n      ],\n      \"caption\": \"List of sites\"\n    }\n  ]\n}\n[/block]\nClick on the **\"MyPortfolio\"** site and in the next screen, in the left sidebar, click on the **\"Projects\"** page.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ZhdHoIKGQtK7xybNxZQ8_second.png\",\n        \"second.png\",\n        \"2876\",\n        \"1597\",\n        \"#266299\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nYou can edit the text on the right sidebar and see instantaneously the result on the left side.\n\nIf you want to add your first project, in right sidebar, click on the \"**Manage**\" button just beside \"**Projects**\". In the next screen displaying all the projects (none for now), click on the \"New entry\" button. Fill the form and save your project.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/kroUjFYTkmfifeB9NsnL_third.png\",\n        \"third.png\",\n        \"2876\",\n        \"1597\",\n        \"#334a5e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nFinally, go back to your \"**Projects**\" page. You should see your first project!\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Dy71Bnx6SMSrK034wQif_fourth.png\",\n        \"fourth.png\",\n        \"2876\",\n        \"1597\",\n        \"#29649a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What next?\"\n}\n[/block]\nIn less than 5 minutes, you were able to create a simple portfolio and generate nice looking back-office to edit the content of your site.\n\nThe site needs definitively a custom design. How to do it? Very simple, go back to your Wagon files and tweak your application.css file. \n\nYou want to add a blog? Well, that's also an easy task. Create the right content type (blog posts for instance?) and write the pages to display your posts.\n\nWhen you're done, just deploy your changes with the **wagon deploy** command!","category":"571a587304c2a32b00a1d5d3","createdAt":"2015-11-10T13:28:46.861Z","excerpt":"Create a simple portfolio site and its back-office interface in 5 minutes","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"parentDoc":null,"project":"5559cc52dab6630d0079274d","slug":"quick-start","sync_unique":"","title":"Quick start","type":"basic","updates":["5693fc0b5f1c951900644c41","5693fcc873f48f0d0075c9b5","5695dea6fe18811700c9c15a","569fcc55a454d2230002cbb5","57e2457e18164d0e0062141d"],"user":"542a837b54d88d140075facb","version":"571a587304c2a32b00a1d5d2","childrenPages":[]}

Quick start

Create a simple portfolio site and its back-office interface in 5 minutes

Before starting, you need to make sure your system has Ruby 2.1 (or upper) installed. If it is not the case, please follow the **first two steps** of the **[following tutorial](https://gorails.com/setup/osx/10.9-mavericks)**. [block:api-header] { "type": "basic", "title": "1. Install Wagon" } [/block] Wagon is a command line tool that let's you develop for Locomotive right on your local machine. With Wagon, you can generate the scaffolding for a new Locomotive site and start adding the content types and templates you need using any text editor. And thanks to Wagon's built-in web server, you can preview the site with your computer's web browser. Wagon can also deploy sites to any Locomotive Engine using the wagon **deploy** command. Your changes will immediately be reflected on that site without restarting or making any changes to the Engine server app. To help you work faster, Wagon comes with support for tools like SASS, HAML, and CoffeeScript. It also works well with source version control systems like git and svn. [block:code] { "codes": [ { "code": "gem install locomotivecms_wagon", "language": "shell" } ] } [/block] Make sure it has installed the very last version of Wagon **2.1.0** by typing the following command in your terminal. [block:code] { "codes": [ { "code": "wagon version", "language": "text", "name": "Shell" } ] } [/block] [block:callout] { "type": "warning", "title": "\"The program 'wagon' is currently not installed\" error", "body": "If you use **rbenv** to manage your ruby installations, you need to run ````rbenv rehash````." } [/block] [block:callout] { "type": "info", "title": "For advanced users: install it with Devstep and Docker", "body": "We wrote a guide describing all the steps. It can be found [here](/v3.0/docs/install-wagon-using-devstep-and-docker)" } [/block] [block:callout] { "type": "info", "title": "The Locomotive.works platform", "body": "We offer Locomotive site hosting services with a limited free plan. Check out [our site](http://locomotive.works#pricing) for more information." } [/block] For practical reasons, we will use [Locomotive.works](http://locomotive.works) as our deployment target but you're absolutely free to use your own Engine on EC2, Digital Ocean, Engine Yard, Linodes, Heroku or your own server. Don't forget, everything is open source here. [block:code] { "codes": [ { "code": "wagon auth", "language": "shell" } ] } [/block] If you don't have an account, it will create one for you. [block:api-header] { "type": "basic", "title": "2. Create a new Wagon site" } [/block] We start with our built-in Bootstrap site template which embeds the last version of [Bootstrap](http://getbootstrap.com), the popular HTML/CSS framework. [block:code] { "codes": [ { "code": "mkdir -p ~/Sites/Wagon\ncd ~/Sites/Wagon\nwagon init MyPortfolio -t bootstrap\n# Use y or n when questions are promted\ncd MyPortfolio\nbundle install", "language": "shell" } ] } [/block] Now, let's launch the Wagon preview server. [block:code] { "codes": [ { "code": "bundle exec wagon serve ", "language": "shell", "name": "" } ] } [/block] Open your browser at this address **http://localhost:3333/**, you should see a minimal [Bootstrap](http://getbootstrap.com) site. [block:api-header] { "type": "basic", "title": "3. Define a content type" } [/block] One essential feature of any CMS is the ability to manage structured content. Fortunately, this is one of Locomotive's strongest points. For our portfolio site, let's say we want to manage a list of our client projects. Those projects are defined by a name, a client name, a description and an image. **Wagon** includes a number of built-in generators, "content_type" is one of them. [block:code] { "codes": [ { "code": "bundle exec wagon generate content_type projects name:string client:string description:text image:file", "language": "shell" } ] } [/block] This command generates 2 files: - **app/content_types/projects.yml**: It defines the content type. - **data/projects.yml**: Auto-generated list of project samples. [block:api-header] { "type": "basic", "title": "4. Build the page listing the projects" } [/block] **Liquid** is our powerful templating language. Among a lot of functionalities, it has access to the content types. First, let's generate our page. [block:code] { "codes": [ { "code": "bundle exec wagon generate page projects", "language": "shell" } ] } [/block] Open the **app/views/pages/projects.liquid** page in your code editor and replace the liquid code below the second **"---"** (line 24) with the following code which lists all the projects in Liquid. [block:code] { "codes": [ { "code": "{% extends 'layouts/simple' %}\n\n{% block content/main, short_name: true %}\n\n{% editable_model projects %}\n<div class=\"row\">\n <div class=\"col-sm-12\">\n {% for project in contents.projects %}\n <div class=\"media\">\n <div class=\"media-left\">\n <img class=\"media-object\" src=\"{{ project.image.url | default: 'http://loremflickr.com/100/100' | resize: '100x100#' }}\" alt=\"{{ project.name }}\">\n </div>\n <div class=\"media-body\">\n <h4 class=\"media-heading\">{{ project.name }}</h4>\n <p><strong>Client:</strong> {{ project.client }}\n <div>\n {{ project.description }}\n </div>\n </div>\n </div>\n {% endfor %}\n </div>\n</div>\n{% endeditable_model %}\n\n{% endblock %}", "language": "liquid" } ] } [/block] If you refresh your browser, you will notice that a new link ("Projects") appeared at the top right corner of the page. Click on it and you will see all our samples defined in **data/projects.yml**. [block:api-header] { "type": "basic", "title": "5. Deploy the site" } [/block] Now we have a working Wagon site, we want to see it working online, with the backoffice and everything. That's the role of the Locomotive engine. Now, let's deploy our site! [block:code] { "codes": [ { "code": "bundle exec wagon deploy live", "language": "text" } ] } [/block] Since the site doesn't exist yet on the Locomotive engine, you will be asked for a couple of information about it. [block:api-header] { "type": "basic", "title": "6. Modify the live content of your site!" } [/block] Go to [locomotive.works](https://station.locomotive.works/_app/sign_in) and sign in with the credentials you entered in the first step. Then, you will see the following screen: [block:image] { "images": [ { "image": [ "https://files.readme.io/m7LYIsEvTWax458jOkNJ_first.png", "first.png", "2876", "1597", "#4193d7", "" ], "caption": "List of sites" } ] } [/block] Click on the **"MyPortfolio"** site and in the next screen, in the left sidebar, click on the **"Projects"** page. [block:image] { "images": [ { "image": [ "https://files.readme.io/ZhdHoIKGQtK7xybNxZQ8_second.png", "second.png", "2876", "1597", "#266299", "" ] } ] } [/block] You can edit the text on the right sidebar and see instantaneously the result on the left side. If you want to add your first project, in right sidebar, click on the "**Manage**" button just beside "**Projects**". In the next screen displaying all the projects (none for now), click on the "New entry" button. Fill the form and save your project. [block:image] { "images": [ { "image": [ "https://files.readme.io/kroUjFYTkmfifeB9NsnL_third.png", "third.png", "2876", "1597", "#334a5e", "" ] } ] } [/block] Finally, go back to your "**Projects**" page. You should see your first project! [block:image] { "images": [ { "image": [ "https://files.readme.io/Dy71Bnx6SMSrK034wQif_fourth.png", "fourth.png", "2876", "1597", "#29649a", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "What next?" } [/block] In less than 5 minutes, you were able to create a simple portfolio and generate nice looking back-office to edit the content of your site. The site needs definitively a custom design. How to do it? Very simple, go back to your Wagon files and tweak your application.css file. You want to add a blog? Well, that's also an easy task. Create the right content type (blog posts for instance?) and write the pages to display your posts. When you're done, just deploy your changes with the **wagon deploy** command!