In this article, we will look at how to use Grav with GitHub Desktop and Beanstalk (which has automatic FTP deployment built-in) to provide a highly efficient workflow when updating your Grav site, and source control to boot. While GitHub only offers private repositories for paid plans, Beanstalk offers a free plan to store one single repository privately.

You will be required to enter a few commands into your Mac or PC command line interface (CLI) during this the process, so get comfortable and let’s get started.

This article will be substantially updated once the pre-release Git Sync plugin for Grav is officially released (expected in February).

Step-by-step instructions

  1. Download and unzip a Grav Skeleton of your choice.

  2. Download the GitHub Desktop client for your computer (Mac or PC), and once it is installed launch the application. Since you will be using Beanstalk, and not GitHub, you can skip the setup process at this time.

    GitHub Desktop setup welcome
    Figure 1. GitHub Desktop setup welcome.

  3. Once the GitHub Desktop application is installed, you will need to install it’s command line tools. This option can be found in the GitHun Desktop’s ‘Preferences’ dialog on the ‘Advanced Panel’ - look for the ‘Install Command Line Tools’ button and then press it.

    GitHub Desktop preferences dialog with the 'install command line tools button
    Figure 2. GitHub Desktop preferences dialog with the ‘install command line tools button.

  4. Head over to Beanstalk and sign-up for a free account (one user private project plan with 100MB of storage).

    Beanstalk homepage
    Figure 3. Beanstalk homepage.

  5. Once you have signed up and are signed-in, create a new repository by pressing the “Create a Repository” button.

    Beanstalk welcome page
    Figure 4. Beanstalk welcome page.

  6. Next, enter the name of your new repository. Consider the name of the Grav project you will eventually be storing when choosing the name. Once you enter the repository name press the ‘Next Step’ button.

    Beanstalk new repository
    Figure 5. Beanstalk new repository.

    You will next need to make the initial commit to your newly created Beanstalk repository. Launch the command line interface for the Mac OS, which is the ‘Terminal’ app, or if you are on Windows launch the ‘Git Shell’ app which would have been installed along with GitHub Desktop (within the same application folder).

    Mac OS Terminal application
    Figure 6. Mac OS Terminal application.

  7. To streamline the need to navigate directories during this process, I would suggest you place your previously unzipped Grav Skeleton folder to where you wish to eventually maintain it (e.g. in your ‘Documents’ folder). For this operation you will be using the ‘cd’ command, which is for change directory. In your CLI enter ‘cd’, press the space bar, and then drag-and-drop the folder that contains your Grav Skeleton folder (not the actual Grav Skeleton folder) onto the CLI window. With the full path to the folder now after the ‘cd’ command press the ‘Return’ key.

    Mac OS Terminal application with folder dropped after 'cd' command Figure 7. Mac OS Terminal application with folder dropped after ‘cd’ command.

    To make sure you are at the correct directory level, you can use the ‘ls’ command, which is for listing the files stored in a directory. In your CLI, enter ‘ls’ and press the ‘Return’ key. You should see the name of your Grav Skeleton folder in this list (e.g. within your ‘Documents’ folder).

    Mac OS Terminal application with ls command entered
    Figure 8. Mac OS Terminal application with ‘ls’ command entered.

  8. Now you are ready to link your Grav Skeleton folder to your Beanstalk repository by copying the hidden ‘.Git’ folder from the cloned repository to your actual Grav Skeleton folder. Return to your Browser and copy the ‘Git repository URL’ field which should be displayed on the current Beanstalk site page.

    Beanstalk repository, with Git URL
    Figure 9. Beanstalk repository, with Git URL.

  9. Return to your CLI window, and type ‘git clone’, plus a space, and then paste the Git repository URL you have just copied to your clipboard, then a space, and finally the text ‘temp’. This command will clone your Beanstalk repository to your computer within a folder called ‘temp’. Press the ‘Return’ key to run the entered command. You may also be prompted to enter your Beanstalk username and password for this step.

    Mac OS Terminal application git clone command line entered
    Figure 10. Mac OS Terminal application git clone command line entered.

    After a short period of time a message should be displayed about the status of the Git clone command, such as ‘done’.

    Mac OS Terminal application git clone command completed
    Figure 11. Mac OS Terminal application git clone command completed.

  10. We now need to make the Grav Skeleton folder the location of the repository on your computer, rather than the empty temp folder we just created. To do this, we enter ‘mv temp/.git’, plus a space, then the name of your Grav Skeleton folder, plus a space, followed by ‘/.git’. This operation will by copy the hidden ‘.Git’ folder from the cloned repository to your actual Grav Skeleton folder.

    Mac OS Terminal application move folder command entered
    Figure 12. Mac OS Terminal application move folder command entered.

    Mac OS Terminal application move folder command completed
    Figure 13. Mac OS Terminal application move folder command completed.

    Now that you have your Beanstalk Git repository as your Grav Skeleton folder, you can use GitHub Desktop to easily and quickly send any updates back to the repository on Beanstalk with just a click of the button (no more CLI commands are required!).

  11. Return to the GitHub Desktop app, and press the “Add a Repository” button (upper-right plus(+) sign in the main window) in the GitHub Desktop client, then select the “Add” tab within the displayed dialog box, and press the “Choose…” button to select the folder containing your Grav skeleton.

    GitHub Desktop add Repository dialog
    Figure 14. GitHub Desktop add repository dialog.

    GitHub Desktop local Repository added
    Figure 15. GitHub Desktop local repository added.

  12. You are now ready for the first commit to your new GitHub repository. Whenever you make a commit you will need to include a brief text summary - as this is your first commit enter the text “First commit.” into the “Summary” text box (above the “Description” text field), and then press the button “Commit to master”.

    GitHub Desktop first commit
    Figure 16. GitHub Desktop first commit.

  13. Since this is your first commit to your repository, the “Publish” button (upper-left of main window) may need to be also pressed to perform the actual file updates.

  14. With the files for your Grav Skeleton now uploaded to Beanstalk, the final step is to enter the FTP credentials for your automatic deployments in Beanstalk. Return to the Beanstalk site, navigate to your repository page, and press the “Deployments” button.

    Beanstalk Deployments page
    Figure 17. Beanstalk Deployments page.

  15. Press the ‘Create environment & server’ button and then name your environment. Choose ‘Automatic’ deployments (since you will be doing your development work/testing on your local computer and only commit working versions of your site to Beanstalk).

    Beanstalk Create Environment and Server Page
    Figure 18. Beanstalk Create Environment and Server Page.

  16. Choose the type of server you are adding (most likely FTP or SFTP), press “Next Step”, enter in the needed server address and credentials on the following screen, and then press “Next Step” again. You can skip the ‘Optional Settings’ page when it is shown.

    Beanstalk Add Server
    Figure 19. Beanstalk Add Server.

    Beanstalk Add FTP Server
    Figure 20. Beanstalk Add FTP Server.

    Beanstalk server setup complete
    Figure 21. Beanstalk server setup complete.

    Congratulations! You now have a Grav site which you can run and test locally (using MAMP), and with only one click in the GitHub Desktop application have any changed local site files updated in your Beanstalk private repository and have them automatically pushed to your Web server. In my experience, I can make an update to my Grav site and sync changes to Beanstalk for automatic deployment to my Web server in as little as 30 seconds.

    If you are interested in providing a way for other course facilitators and students to collaborate with your Grav site then you should use a GitHub public repository instead of a private Beanstalk one - read the article Using Grav with GitHub Desktop (and Deploy) for step-by-step instructions.

After my first Grav CMS for Educators Workshop it became apparent I should provide a wider range of options for how Web-savvy instructors can install and set up the flat-file CMS Grav, especially when using my ready-to-run Course Hub package.

So, here are four options for installing and maintaining a Grav site:

1) Web Only

Install Grav on a Web server and maintain the site using the Admin Panel, and when needed an FTP text file editor.

While this is the quickest way to get a Grav site up and running, this approach means that all development is performed on a live website (requiring user authentication).

2) Desktop and Web server (one-time deployment)

Develop the Grav site on your desktop using MAMP, and then deploy the entire site folder to a Web server using an FTP app once the site design is complete. Use the Admin Panel to then maintain the site as needed.

Educators can safely develop and refine their Grav site on their own computer, and once ready for the start of term deploy the site using an FTP app. During the term only page editing is done on the live website (requiring user authentication). If you want to periodically deploy your site during development, I recommend using Cyberduck’s FTP app which includes a ‘Synchronize’ feature.

For a step-by-step guide to installing MAMP locally for use with Grav, read the article Running Grav Locally with MAMP.

3) Desktop and Web server (with on-going automatic deployments)

Both of the following approaches use Git. While there are many benefits of using Git when developing a website, the most crucial one is that it provides very fine control over what (and when) changes are pushed to your live website.

Private Git Repository

Install and maintain the Grav site on your desktop with MAMP and then use GitHub Desktop to quickly sync the site to a private Git repository service as needed for later deployment. If you are looking for a free option to start with, Beanstalk offers a one user private project plan with 100MB of storage and includes automatic site deployment to an FTP Web server.

With a single press of a button, an educator can quickly deploy any updates of their local Grav site to a Web server. Any text editor can also be used to directly modify Grav files locally, as well as the Admin Panel with user authentication.

Public (Collaborative) Git Repository

Install and maintain the Grav site on your desktop with MAMP and then use GitHub Desktop to quickly sync the site to a public GitHub repository (free public projects plan) as needed. Updates are automatically deployed to your FTP Web server via a deployment service and ‘edit this page’ links (via GitHub) can be easily included on site pages (provided with several Grav skeleton packages, including Course Hub and RTFM).

The use of a public GitHub repository is my preferred approach, as in addition to quick automatic deployment of site updates all course materials are public and course participants can collaborate on both the content and behavior of the site.

You can view a step-by-step guide to set up Grav with GitHub in the article Using Grav with GitHub Desktop (and Deploy).

If you are comfortable with the command line of Git, you might also want to check out these two super informative articles on the Grav website:

This is a brief guide to help tech-savvy educators ‘flip’ their LMS with the modern flat-file (no database) CMS Grav and my open source Course Hub skeleton package.

Grav Course Hub Screenshot

This guide is now outdated. View the updated Open Course Hub documentation on the new learn.hibbittsdesign.org site.

Table of Contents
Course Hub Overview
Flipping your LMS with Grav
Installing the Course Hub
Working with Grav
Using Git and GitHub Desktop
Setting Up a Course in Grav Course Hub

Course Hub Overview

The Course Hub skeleton is intended to accompany a face-to-face, blended or fully online university course. It supports a flipped-LMS approach using the modern flat-file (no database) Grav CMS as an open and collaborative Web platform.

Course Hub Features

  • A complete ready-to-run Grav package (Source on GitHub)
  • Blog-format, with ‘featured’ (sticky) posts
  • Single course per Hub, multiple courses per Hub or even multiple course sub-sites (blog + multiple pages per course) per Hub
  • Optional important reminders & class preparations areas
  • Hub pages can be easily added/removed/changed
  • Uses Markdown for streamlined cross-platform content
  • Image header area above Hub navigation bar
  • Sidebar is a simple markdown file, which can also contain HTML
  • URL flag to only display page content (for display within LMS). For example, http://demo.hibbittsdesign.org/grav-course-hub-bootstrap/home/week-03/onlydisplaypagecontent:true
  • External links are automatically opened in a new Tab/Window
  • Built-in support for entire Hub to be collaboratively maintained on GitHub or GitLab (for local hosting)
  • Since everything is built with Grav it can be entirely customized

Required Technical Skills

  • Code editor usage (e.g. Atom or Brackets)
  • Markdown or HTML basics
  • Understanding folder hierarchies (i.e. relative links)
  • Webserver access
  • GitHub working knowledge (recommended)

Flipping your LMS with Grav

What is a Flipped LMS?

A flipped LMS approach is where an open platform, in the control of course participants, serves as an alternative front-end to the institutional LMS.

Flipped-LMS approach
Figure 2. Flipped-LMS approach.

Why Flip your LMS?

  • To support pedagogical goals unmet by current LMS/platform
  • To deliver a better student (and facilitator) experience
  • To increase capability of access, sharing and collaboration

Why Use a Modern Flat-file CMS?

As an open source modern flat-file CMS, Grav offers a distinct set of advantages to Web-savvy educators looking to move beyond their institutional LMS:

  • Modern means…
    • Use of current standards (i.e. Markdown, Twig, YAML, etc.)
    • Modular/customizable content chunks (i.e. reuse of content)
    • Further separation of content (i.e. files) from presentation
  • Flat-file means…
    • No database means less (or no) IT involvement needed
    • Content stored in text files rather than in a database
    • In many cases, this translates into faster page access times
    • Increased portability, as moving a site now only requires simply copying files to another location
    • Takes full advantage of the collaborative ecosystem now available (i.e. GitHub, GitLab, etc.)

Want to learn more about flipping your LMS with an open and collaborative platform such as Grav? Explore more visualizations in the article Flipped-LMS Approach Using an Open and Collaborative Web Platform

Installing the Course Hub

Web Only (Quick Install)

Pre-flight Checklist

  1. Confirm Webserver PHP version (PHP 5.5.9 or higher)
  2. Webserver login credentials (username and password)

Installation Steps

  1. Download the ready-to-run Course Hub Skeleton Package (GitHub Repo)
  2. Unzip the package onto your desktop
  3. Copy the entire Grav Course Hub folder to your Webserver
  4. Point your browser to the Webserver folder
  5. Create your site administrator account when prompted
  6. And you’re done! (press the icon in the Admin Panel to preview site)

Desktop and Webserver (Recommended Install)

Pre-flight Checklist

  1. Confirm Webserver PHP version (PHP 5.5.9 or higher)
  2. Download and install MAMP (https://www.mamp.info/)

Desktop Installation Steps

  1. Download the ready-to-run Course Hub Skeleton Package (GitHub Repo)
  2. Unzip the Grav package onto your desktop
  3. Create a folder called ‘MAMP Websites’ in your ‘Documents’ folder
  4. Copy the entire Grav folder into your ‘MAMP Websites’ folder
  5. Launch MAMP
  6. Change the ‘Document Root’ setting on the MAMP preferences ‘Webserver’ tab to the ‘MAMP Websites’ folder (within ‘Documents’)
  7. Press the MAMP ‘Start Servers’ button
  8. Enter ‘localhost:8888’ as the URL in your Web Browser
  9. Choose the displayed Grav folder name
  10. Create your site administrator account when prompted
  11. And you’re done! (press the icon in the Admin Panel to preview site)

If you would like a more detailed step-by-step guide to the above desktop installation process, please see the article Running Grav Locally with MAMP.

Now that you have a Grav site running on your computer you need to sync those site files to your Webserver. My preferred method is to use a public GitHub (Git) repository (to enable contributions by course participants) and an automatic deployment service, as described in the post Using Grav with GitHub Desktop. If you want to keep your source files to yourself, then using a private Beanstalk repository would be a no-cost option as described in the post Using GitHub Desktop and Beanstalk with Grav.

If you are interested in storing your Git repository on your own servers, then the open source tool GitLab could be an option, as described in the post Using GitHub Desktop and GitLab with Grav.

Working with Grav

Now that the Grav Course Hub is up and running you are ready to start working with Grav! To learn how Grav is organized, and how to add and edit pages, read the Grav Basic Tutorial.

You can view the all of the official Grav documentation at learn.grav.org. If you are looking for additional help check out the Getting Help section.

Grav for Educators Workshop Slides

If you are new to Grav, you might find these workshop slides helpful: Moving Beyond the LMS with Grav Slides

Using Git and GitHub Desktop

Setting up a Course

For details about configuring and further customizing the Grav Course Hub read Setting Up a Course in the Grav Course Hub.


Suggestion or corrections to this guide? Edit this Page on GitHub

Here is the list of resources for participants in my Grav CMS for Educators workshops (bit.ly URL is http://bit.ly/1PDs3N8):

Grav Skeletons

Course Hub Documentation

  • Demo (demo.hibbittsdesign.org/grav-course-hub/)
  • ReadMe (github.com/hibbitts-design/grav-skeleton-course-hub/blob/master/README.md)
  • GitHub Repository (github.com/hibbitts-design/grav-skeleton-hub-companion/)

Suggested Desktop Toolset

Installation

Web Install

Pre-flight Checklist

  1. Confirm Web server PHP version (PHP 5.5.9 or higher)
  2. Web server login credentials (username and password)

Installation Steps

  1. Download a Grav Skeleton from this page (see above list)
  2. Unzip the package onto your desktop
  3. Copy the entire Grav folder to your Web server
  4. Point your browser to the Web server folder
  5. Create your site administrator account when prompted
  6. And you’re done! (press the icon in the Admin Panel to preview site)

Desktop Install

Pre-flight Checklist

  1. Confirm Web server PHP version (PHP 5.5.9 or higher)
  2. Download and install MAMP (mamp.info)

Desktop Installation Steps

  1. Download a Grav Skeleton from this page (see above list)
  2. Unzip the Grav package onto your desktop
  3. Copy the entire Grav folder into the ‘htdocs’ folder within your MAMP application folder
  4. Launch MAMP
  5. Press the MAMP ‘Start Servers’ button
  6. Enter ‘localhost:8888’ as the URL in your Web Browser
  7. Choose the displayed Grav folder name
  8. Create your site administrator account when prompted
  9. And you’re done! (press the icon in the Admin Panel to preview site)

Now that you have a Grav site present on your computer you can sync those site files to your server in the future, as described in the post Using Grav with GitHub Desktop (hibbittsdesign.org/blog/posts/2015-12-11-using-grav-with-github).

Markdown Documentation

Grav Documentation (learn.getgrav.org/)

Git and GitHub Desktop Overview

Grav for Educators Workshop Slides

I came across this tweet today, thanks to the @getgrav Twitter feed:

This is something I can definitely speak to, as in fact just over a year ago I tried out each of the above CMSs (and a few others) for use as a new course website platform. Here is a little trip down memory lane…

I even went ahead and purchased a single user Statamic 1.0 license, as there was no free trial available at the time. As you can see from the above, I also checked out OctoberCMS and Bolt during my evaluation phase.

For each CMS I tried to modify either a default site and/or start a new simple project site. I was able to do this with each CMS easily enough, but found the CraftCMS had the most feature-rich editing environment and a very strong modular content approach as well. Statamic was also quite promising initially, but I soon ran into several difficulties including getting the available Foundation theme handling dropdown menus. Overall, I found that things work the easiest for me with OctoberCMS, Kirby, Bolt, and Grav.

All of the above CMSs are also “modern” in general terms, but as I learned more about what a flat-file CMS could specifically provide I decided to focus on that aspect.

Some key benefits of flat-file CMSs, especially for educators:

  • No database means less (or no) IT involvement needed
  • Increased portability, as moving a site now only requires simply copying files to another location
  • Takes full advantage of the collaborative ecosystem now available (i.e. GitHub, GitLab, etc.)

Once I decided that a flat-file CMS was the best fit for my needs, then OctoberCMS, CraftCMS, and Bolt were all eliminated from the running. I also wanted to use an open source platform, so that then removed Statamic from the running.

So why did I choose RocketTheme’s Grav over Kirby given my initial analysis? After a bit of thought, I would say the main reasons were:

  • Excellent conceptual/design model
  • Markdown/Twig/YAML usage
  • Self-contained Skeleton format
  • Inherited themes
  • Multiple open-source themes suitable for my needs
  • Powerful modular content support
  • Custom content type definitions
  • File editing and/or fully-featured Web editor (which was planned for Grav 1.0)
  • Documentation quality (bonus points: it’s built with Grav learn.grav.org)
  • Level of community support/engagement
  • Example GitHub integration (which also supports my current preferred workflow)

Speed/responsiveness was also an important consideration, but based on my initial experiences Grav and Kirby seems pretty evenly matched on that issue.

It’s just over a year later and I am feeling really good about my choice. Grav v1.0 has now been released, and both its capabilities and the community keep growing. A public roadmap for Grav in 2016 is available which also includes Gantry 5, RocketTheme’s theme framework available on Joomla and soon on Wordpress. From everything that I’ve seen so far Gantry will bring some really easy-to-use but powerful theme customization features to Grav.

As a side-note, I’ve also used other platforms such as WordPress, Concrete5, and Moodle to create my course hubs in the past, but with Grav I’ve been able to achieve a much higher level of customization than ever before. With only basic HTML/CSS knowledge, coupled with the incredible ease of use of the Twig language, Grav has enabled me to design and deliver much better experiences for my students and fellow educators. I’ve even been able to create my own open source Course Hub project to help other educators get started with Grav, which I plan to also release as a self-contained Grav skeleton package.

Want to read a more detailed overview of Grav? Check out David Walsh’s article Grav: Building Fast and Flexible Websites.

I look forward to reading Patrick’s CMS comparison article next!

I am putting together a very brief presentation about flipping an LMS with an open + collaborative platform. Here is what I’ve got so far:

Flip it Good! Flipping the LMS with an Open + Collaborative Platform
Do you have unmet pedagogical goals due to the constraints of your current LMS? Do you want to have a better experience for your students and yourself? In preparing his Fall 2015 CMPT-363 (User Interface Design) course at Simon Fraser University, instructor and interaction designer Paul Hibbitts faced these same challenges. His solution was to ‘flip the LMS’ by designing and developing an alternative front-end to the institutional LMS Canvas (http://paulhibbitts.net/cmpt-363-153/). In this approach, the LMS was used only for elements it was best suited for (i.e. student records, grades, etc.) with all other elements handled by an open extensible platform completely under his control.

Based on the positive feedback of his students and his own experience, he decided to create an open source course hub built with the CMS (Content Management System) Grav to help other instructors get started in flipping their LMS with an open + collaborative platform.

In this presentation Paul will share his flipped-LMS approach and introduce his ready-to-run open source Grav Course Hub for use by other educators.

In-progress Slides

This article is now outdated. Please refer to the Grav Course Companion Getting Started Guide.

I am pleased (well, actually quite stoked) to announce that my ready-to-run Course Companion, built with the open source CMS Grav, is now available for fellow educators to take for a test drive.


Continue Reading

Here is a quick sampling of some Grav CMS Course Companion workflows:


Video 1. Simple install of the course companion on a Web server (in under 30 seconds).



Video 2. Instructor workflow of making a course companion edit and pushing change to live site (recommended desktop and server install).



Video 3. Student workflow of making a suggested change to the course companion (optional feature).



Video 4. Instructor review of proposed student changes to the course companion site (optional feature). Appointed students can also have the ability to review and approve submitted changes.