How to Set Up Grav CMS (Flat-File)

How to Set Up Grav CMS (Flat-File)

Grav is a modern, open-source flat-file CMS that requires no database. Content is stored as Markdown files on disk, making it incredibly fast and easy to version-control. With its powerful templating engine (Twig), flexible taxonomy system, and built-in admin panel, Grav is an excellent choice for developers and content creators who want simplicity without sacrificing power.

Why Choose a Flat-File CMS

• No database required — eliminates an entire class of security vulnerabilities and maintenance overhead
• Version control friendly — your entire site can be tracked in Git
• Easy backups — just copy the files, no database exports needed
• Portable — move your site by simply copying the directory
• Fast — no database queries means faster page loads

Prerequisites

• A Breeze instance running Ubuntu 22.04 or later
• PHP 8.1+ with CLI and required extensions
• Apache or Nginx web server
• No database needed

Step 1 — Install PHP Extensions

sudo apt update
sudo apt install -y php-curl php-gd php-mbstring php-xml php-zip php-yaml php-opcache

Step 2 — Download and Install Grav

Download the Grav package with the Admin plugin included:

cd /tmp
wget https://getgrav.org/download/core/grav-admin/latest -O grav-admin.zip
sudo unzip grav-admin.zip -d /var/www/
sudo chown -R www-data:www-data /var/www/grav-admin
sudo chmod -R 775 /var/www/grav-admin

Step 3 — Configure Apache

sudo nano /etc/apache2/sites-available/grav.conf

<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /var/www/grav-admin

    <Directory /var/www/grav-admin>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/grav_error.log
    CustomLog ${APACHE_LOG_DIR}/grav_access.log combined
</VirtualHost>

sudo a2ensite grav.conf
sudo a2enmod rewrite
sudo systemctl reload apache2

Step 4 — Create Your Admin Account

Navigate to http://yourdomain.com/admin in your browser. Grav will prompt you to create the first admin account. Fill in your username, email, and password to access the admin panel.

Step 5 — Create Content

Grav stores content as Markdown files in the user/pages/ directory. Each page is a folder containing a Markdown file:

/user/pages/
  01.home/
    default.md
  02.about/
    default.md
  03.blog/
    blog.md
    my-first-post/
      item.md

Each Markdown file contains YAML front matter followed by content:

---
title: My First Post
date: 2025-01-15
taxonomy:
    category: [blog]
    tag: [tutorial, getting-started]
---

# My First Post
This is my first blog post on Grav CMS.

Step 6 — Install Plugins and Themes

Use the Grav Package Manager (GPM) to install extensions:

cd /var/www/grav-admin
bin/gpm install sitemap
bin/gpm install feed
bin/gpm install pagination

Browse available themes and switch from the admin panel under Themes.

Maintenance

• Back up your site by archiving the entire Grav directory: tar -czf grav-backup.tar.gz /var/www/grav-admin
• Update Grav and plugins: bin/gpm self-upgrade && bin/gpm update
• Clear cache when needed: bin/grav cache