Installing Grav (a flatfile alternative to WordPress?) on Ubuntu 16.04

Jump down to “1. Install” if you just want the five-minute walkthrough I worked out for Ubuntu 16.04.

Grav Backend
Grav Backend

0. Background

I recently ran across Grav, “A modern open source flat-file CMS”. It looks like a promising alternative to WordPress that should be easier to customize to do what I want.

The lack of a need for a database should make installing on servers less painful as well. I also like the idea of writing in my posts in Markdown by default — I often struggle on my current wordpress-based blog with formatting issues. However, I still want drag-and-drop image support, since many of my blog posts are image heavy.

Additionally, last year (for grad school applications) I made an attempt at a separate portfolio site, using Jekyll with the Freelancer theme by Start Bootstrap. However, it left to be desired in terms of ease of updating and more.

Screenshot from 2016-11-24 17:58:47
My portfolio site, nancyouyang.com || https://github.com/nouyang/nouyang.github.io

I took a chance and tried out Grav, and really liked what I saw.

Grav Admin Interface
Grav Admin Interface
Grav Drag and Drog Image GUI
Grav Drag and Drog Image GUI

 

Screenshot from 2016-11-24 17:20:30
Grav Markdown Page Editor
Grav TwentyFifteen Skeleton (a port of WordPress TwentyFifteen theme)
Grav TwentyFifteen Skeleton (a port of WordPress TwentyFifteen theme)

I can already see some cons, though. For one, it’s not easy to tell which themes are compatible with your existing site structure.

Oh well, maybe in a few years something better will come along. I decided I was intrigued enough to sink a few days into learning how to operate and customize Grav.

1. Install

The main errors I worked through were a missing PHP module and a permissions error.

(Some of these errors only showed up when I saved a page or tried to upload an image. See section 3 for the exact errors I was getting).

Note: I chose to install under /var/www/html/grav so everything shows up at http://localhost/grav, but you can definitely do everything directly under /var/www/html

From the grav homepage, https://getgrav.org/, go to Downloads, and then to Skeletons.

We will be using a Grav Skeleton, specifically the one called “TwentyFifteen Site”.

A Grav Skeleton is effectively an all-in-one sample site. They include the Grav Core, required plugins, as well as appropriate pages for content and a theme for pulling it all together. [src]

SSH / Login to your server.

Note: Apache2 should already be installed by default. If you go to /var/www/html you should find an index file (“Apache2 Ubuntu Default Page”) that should also show up when you go to either localhost or your domain name (e.g. http://your-site.com) in your browser.

sudo apt-get install unzip
cd /var/www/html 
wget 
https://github.com/getgrav/grav-skeleton-twentyfifteen-site/releases/download/1.0.3/grav-skeleton-twentyfifteen-site-v1.0.3.zip
sudo unzip grav-skeleton-twentyfifteen-site-v1.0.3.zip
mv grav-skeleton-twentyfifteen-site-v1.0.3.zip grav
cd grav
sudo vi perm.sh
#!/bin/sh
chown www-data:www-data .
chown -R www-data:www-data *
find . -type f | xargs chmod 775
find ./bin -type f | xargs chmod 775
find . -type d | xargs chmod 775
find . -type d | xargs chmod +s
umask 0002
sudo sh ./perm.sh
sudo add-apt-repository universe
sudo apt-get install php7.0-fpm php7.0-cli php7.0-gd php7.0-curl php7.0-mbstring php7.0-zip php-apcu php7.0-xml
sudo service apache2 restart

Go to http://your-site.com/grav/admin (or localhost/grav/admin)

  • You should be prompted to create a user
  • Login to admin
  • http://your-site.com/grav/admin/pages
  • Create and save a page with an image in it

If this works, everything should be great!

2. Troubleshooting

Here I document miscellaneous things I did and tricks I learned.

Permissions

The permissions fix came from Grav documentation, under “11. Troubleshooting” > “Permissions”:

PHP

Grav needs PHP 5.5.9 or higher. https://learn.getgrav.org/basics/requirements

$ php -v

PHP 7.0.8-0ubuntu0.16.04.3

To check which modules are enabled, we can set up use phpinfo()

/var/www/html$ sudo vi test.php
<?php phpinfo(); ?>

Then go to http://localhost/test.php and e.g. search for “mbstring”

Make sure to remove this file after you’re done.

Enable Universe repository

The other issue I ran into was not realizing I couldn’t sudo apt-get install the missing PHP modules because I hadn’t enabled the universe repository.

nrw@the-PC:~$ cat /etc/apt/sources.list

Apache

To enable an Apache module:

$ sudo a2enmod rewrite

(to disable: sudo a2dismod)

$ sudo service apache2 restart

Grav Troubleshooting Features

You can enable the Debug Bar

$ sudo vi /var/www/html/grav/user/config/system.yaml
debugger:
    enabled: true

Also the Error Display

$ sudo vi /var/www/html/grav/user/config/system.yaml
errors:
    display: true

Grav Logs

The logs are at /logs/grav.log

$ tail -f /var/www/html/logs/grav.log

3. Appendix: Errors

The specific errors I encountered

‘mbstring’ extension is not loaded. This is required for Grav to run correctly

Permission denied in /var/www/html/grav/vendor/rockettheme/toolbox/File/src/File.php

0 – An exception has been thrown during the rendering of a template (“The cache/gpm folder is not writable. Please check the folder permissions.”) in “partials/plugins-list.html.twig” at line 19.
if (is_file($path . ‘/’ . $this->_original->name())) {
rename($path . ‘/’ . $this->_original->name(), $path . ‘/’ . $this->name());

“rename(/var/www/html/grav/user/pages/01.blog/new-page/item.md,/var/www/html/grav/user/pages/01.blog/new-page/item.en.md): Permission denied”