Jump down to “1. Install” if you just want the five-minute walkthrough I worked out for Ubuntu 16.04.
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.
I took a chance and tried out Grav, and really liked what I saw.
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”