How to Install Grav (Flat-File CMS) on a VPS

Knowledgebase

Grav is a modern, flat-file CMS — it stores content as files rather than in a database, offering simplicity, speed, and easier version control for content, at the cost of some dynamic features databases typically provide.

What "Flat-File" Means

Instead of storing pages in a database, Grav stores content as Markdown files organized in a folder structure — making content directly readable, easily version-controlled with Git, and eliminating an entire layer of infrastructure (no database server needed at all).

Prerequisites

Ubuntu 22.04/24.04 VPS: 1-2 vCPU, 1-2 GB RAM (genuinely lightweight)
Nginx or Apache, PHP 8.1+
No database required

Step 1 — Install Required PHP Extensions

sudo apt install php8.2-gd php8.2-curl php8.2-mbstring php8.2-xml php8.2-zip -y

Step 2 — Download Grav

cd /var/www
sudo wget https://github.com/getgrav/grav/releases/latest/download/grav-admin.zip
sudo unzip grav-admin.zip
sudo mv grav-admin grav
sudo chown -R www-data:www-data grav

The "admin" variant includes Grav's web-based admin panel; a leaner core-only variant is also available if you prefer editing content files directly.

Step 3 — Configure Nginx

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/grav;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?_url=$uri&$args;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~ /(\.git|cache|bin|logs|backup|webserver-configs)/ {
        deny all;
    }
}

sudo ln -s /etc/nginx/sites-available/grav /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Step 4 — Access the Site

http://yourdomain.com

Step 5 — Access the Admin Panel

http://yourdomain.com/admin

Create your administrator account on first visit.

Step 6 — Add HTTPS

sudo certbot --nginx -d yourdomain.com

Editing Content Directly (Alternative to the Admin Panel)

ls /var/www/grav/user/pages/

Content lives as Markdown files with front-matter metadata — developers comfortable with Git can edit and version-control content directly, entirely bypassing the admin panel if preferred.

Installing Themes and Plugins

bin/gpm install PLUGIN_NAME

Grav's Package Manager (GPM) handles installing themes and plugins from its official repository.

Why Choose Grav Over a Database-Backed CMS

No database server to manage, secure, or back up separately
Content changes can be tracked with standard Git version control
Generally very fast, since there's no database query overhead per page load

Limitations to Consider

Flat-file architecture is less suited to sites needing complex relational content queries, user-generated content at scale, or e-commerce functionality — a good fit for content-focused sites, less so for highly dynamic applications.

Common Errors

404 errors on all pages except the homepage — verify the Nginx try_files directive with the specific _url parameter format Grav requires is correctly configured.

Continue Reading

Browse more articles in CMS Platforms Beyond WordPress.

Knowledgebase

Categories

Categories