Installing Grav

by Gisle Hannemyr

This chapter explains how to download, unpack, install and configure the Grav WCMS on a web server running Ubuntu 18.04 LTS.

Table of contents

Introduction

Before you can start using Grav, you will of course need to install it and set it up to be ready for use. To do so, you need to complete the following steps:

  1. Decide on a host and make sure that Apache and PHP is set up and operational.
  2. Download and install Grav.
  3. Configure.

Decide on a host

Grav is a self-hosted WCMS. Many hosting options exists. My own preference is to use a IaaS cloud service (e.g. a DigitalOcean droplet).

Grav requirements are quite modest and it works under most modern operating systems. The list below shows the development environment preferred by me (YMMV). The square bracket indicates the actual versions provided by Ubuntu 18.04 LTS.

I have not yet fond anyone that has installed Grav on Ubuntu 20.04 LTS, so I defer to try out that platform until somebody else has done it and confirmed that it works.

If you want to use Grav on a host where the Apache web server and PHP are not already installed, you will need install before you can install Grav. You may also need composer. In my notes for web­masters, there is a full chapter about setting up Apache, composer, PHP and other useful tools for a webmaster operating a web server running Ubuntu 18.04 LTS.

Download and install Grav

There are many different ways to download an install Grav. This chapter will just describe two of them:

  1. Install a skeleton by means of a zip archive.
  2. Install the Grav core with composer.

I recommend starting out by installing a skeleton from a zip file. This is by far the quickest way to get a working Grav site up and running.

Whatever installation method you choose, file permission issues seems to part of the initial Grav experience if you run on a Gnu/Linux server. I suspect the design is flawed. Anyway this flaw is fairly easy to mitigate by means of a bash script. I am going to run it in the instructions below, so here it is:

#! /bin/bash
#-------------------------------------------------------------------------------
# Abstract:
#    Script to fix Grav permission issues that may exist on a fresh install or
#    after saving a configuration or content file from the GUI.
#-------------------------------------------------------------------------------
EXIT=13

if [ "$EUID" -ne 0 ]; then
  echo "Please use sudo to run this."
  exit $EXIT
fi

if [ ! -d "cache" ]; then
  echo "No 'cache' directory. Run this in the Grav root and make sure this exists."
  exit $EXIT
fi

chown -R bob.www-data cache
chown -R bob.www-data backup
chown -R bob.www-data logs
chown -R bob.www-data images
chown -R bob.www-data assets
chown -R bob.www-data tmp
chown -R bob.www-data user/accounts
chown -R bob.www-data user/config
chown -R bob.www-data user/data

chmod -R g+w cache
chmod -R g+w backup
chmod -R g+w logs
chmod -R g+w images
chmod -R g+w assets
chmod -R g+w tmp
chmod -R g+w user/accounts
chmod -R g+w user/config
chmod -R g+w user/data

chmod -R a+x bin/gpm

This assumes that the CLI username of the website owner is “bob” and the name of the web server group is “www-data”. Replace this with your own username and the actual name of the web server group when re-creating this script on your own host.

After installing this script in /usr/local/bin, to run it, first change directory to the Grav root, and then run with sudo privileges. If the Grav root is /var/www/example.com/html, then do this:

$ cd /var/www/example.com/html
$ sudo fixgravperms.sh

Install a skeleton by means of a zip archive

A skeleton is an all-in-one package containing the core, a theme, sample pages, plugins, and configuration. It can be considered a “starter-kit” to quickly create a sample website or a demo of a particular theme with a few sample pages. Unlike the core, skeletons are downloaded a zipped archives. Here are is an example og how to install a skeleton provided your the document root in /var/www/html:

$ cd /var/www
$ unzip -q  grav-skeleton-example-site-v1.0.0.zip
$ mv grav-skeleton-example-site html
$ cd html
$ sudo fixgravperms.sh

If you are setting up a vhost anf the document root is (say) “/var/www/example.com/html”, just replace the first line in the recipe above with this:

$ cd /var/www/example.com

The website should now be visible in a browser when you visit the domain configured to point to the web server.

Install the Grav core with composer

If you are familar with the composer dependency manager, you may want to use it to download and install the Grav core instead.

For example, to install Grav for a vhost on the domain “example.com”, do the following.

# Create a directory where the Grav root will be "/var/www/example.com/html".
$ cd /var/www
$ composer create-project getgrav/grav example.com/html

After installaton completes, you should visit the domain where you installed Grav with a web browser. If you don't see the website, but instead a WSOD (White Screen Of death)), this is most likely caused by a file permissions problem. To debug, examine the Apache error log. You will probably see that the cause is that the web server is unable to write to the cache directory and below. To fix this, do:

$ cd /var/www/example.com/html
$ sudo chgrp -R www-data cache

After doing this, you should be able to see the the Grav startup page. It will also do a sanity check and you may see some errors that need to be fixed. For instance, you may be asked to tweak files permissions. The folders that need to be fixed appear below this:

Essential Folders: There were problems with required folders

To fix it, including some folders that will be required the web server group to own it later, use the bash script created prerviously. I.e. do this:

$ cd /var/www/example.com/html
$ sudo fixgravperms.sh

After all errors has been cleared up, the first time it loads, Grav pre-compiles some files. If you now refresh your browser, you will get a faster, cached version. The top of the page looks like this:

grav_start.png
The top of the start up page after completing the installation.

To check the version number, run this from grav webroot:

$ bin/gpm version -f
You are running     v1.6.24

tipYou must be in the webroot to run this command. If you try to run it from somewhere else, you get: “FATAL: Must be run from ROOT directory of Grav!”

Configure

After Grav has been successfully you may want to configure the website.

Tweaks

To allow any password, have this line in “user/code/system.yaml”.

pwd_regex:  '.*'

Translations

The global translations files are .yaml-files that lives in the directory called “system/languages”. Two character ISO 639-1 codes are used to identify language. For instance, the Norwegian (bokmål) language file is: “system/languages/nb.yaml”.

Plugins keep their translations in a directory called languages below their root. For instance, the translations for the Admin plugin is: user/plugins/admin/languages/.

On a multilingual site, translated pages must have the ISO 639-1 code as part of the file name (e.g: “default.nb.md”).

noteThe language switcher rely on the ISO 639-1 code for locating the language files and the translated pages on a multilingual site. The Grav development community seems to be sloppy about what codes they use. For instance, some plugins and themes use the code “no” instead of “nb” for Norwegian (bokmål). If you run a multilingual site, you need to rename those that are wrong to make them visible to the language switcher.

Configure email

Does not work by default.

[TBA]

Final word

Installation is only a job well begun. The task of running a production Grav site entails keeping the configuration up to date. Some of the updates to the Grav core and plugins that appear over time are security updates. Failing to install them in a timely manner when they become available constitutes a security risk.

In a professional enviroment, you will build a Grav website on a staging server located behind a firewall and not accessible from outside your organisation. When the site has been built, it will be copied to a production server to “go live” on web.

Below are links to other web pages with instructions for installing Grav on Ubuntu 18.04 LTS. You may want to visit those to see alternative installation instructions to those provided above. Most of these use wget to install Grav.

Last update: 2020-05-13 [gh].