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, ||

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,, 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. in your browser.

sudo apt-get install unzip
cd /var/www/html 
sudo unzip
mv grav
cd grav
sudo vi
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 ./
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 (or localhost/grav/admin)

  • You should be prompted to create a user
  • Login to admin
  • 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.


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


Grav needs PHP 5.5.9 or higher.

$ 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


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
    enabled: true

Also the Error Display

$ sudo vi /var/www/html/grav/user/config/system.yaml
    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/,/var/www/html/grav/user/pages/ Permission denied”