# Grav CMS

> Modern flat-file CMS with no database required.

- Category: CMS & Blogging
- Difficulty: beginner
- Components: grav
- Tags: grav, flat-file, markdown, php
- Source: https://docker.recipes/cms/grav-cms

## Overview

Grav is a modern flat-file Content Management System built on PHP that stores content in Markdown files instead of a database. Developed by RocketTheme, Grav emerged as a response to the complexity and security vulnerabilities of traditional database-driven CMS platforms like WordPress and Drupal. By eliminating the database layer entirely, Grav offers faster performance, simpler backups, and Git-friendly version control for content management. The LinuxServer.io Grav image provides a containerized environment with proper file permissions and timezone handling, running on Apache with PHP 8.x support. This flat-file architecture makes Grav exceptionally portable and eliminates common database-related issues like connection failures, corruption, or migration complexity. Content creators and developers benefit from Grav's Twig templating engine, extensive plugin ecosystem through GPM (Grav Package Manager), and the ability to edit content directly in Markdown files or through the optional Admin plugin interface.

## Features

- Flat-file architecture with Markdown content storage eliminating database dependencies
- Twig templating engine with flexible theme customization and inheritance
- GPM (Grav Package Manager) for one-click plugin and theme installation
- Built-in Markdown Extra support with custom shortcodes and macros
- Multi-language content support with automatic language detection
- YAML-based configuration with environment-specific overrides
- Responsive Admin Panel plugin for content management through web interface
- Git-friendly content workflow enabling version control for pages and media

## Use cases

- Developer portfolios and documentation sites requiring version-controlled content
- Small business websites needing fast loading times without database overhead
- Marketing agencies managing multiple client sites with simplified deployment
- Technical blogs and knowledge bases leveraging Markdown writing workflows
- Prototype and staging environments where database setup adds complexity
- Educational institutions creating course materials with collaborative editing
- Personal blogs and creative portfolios prioritizing simplicity and performance

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration
- Minimum 512MB RAM allocated for PHP processes and file caching
- Port 8080 available on host system for web interface access
- Basic understanding of Markdown syntax for content creation
- Familiarity with YAML configuration files for Grav settings
- Knowledge of Twig templating for theme customization (optional)

## docker-compose.yml

```yaml
services:
  grav:
    image: linuxserver/grav:latest
    container_name: grav
    restart: unless-stopped
    environment:
      PUID: 1000
      PGID: 1000
      TZ: UTC
    volumes:
      - grav_config:/config
    ports:
      - "8080:80"

volumes:
  grav_config:
```

## .env

```bash
# No database required - flat-file CMS
```

## Usage notes

- Docs: https://learn.getgrav.org/
- Access at http://localhost:8080
- Install Admin plugin: bin/gpm install admin, then /admin
- Content stored as Markdown files in user/pages/
- Flat-file: no database, easy backups, Git-friendly
- Twig templating, extensive plugin ecosystem

## Troubleshooting

- Permission denied errors accessing /config: Ensure PUID/PGID match host user ownership of mounted volumes
- Admin plugin not found after installation: Restart container after GPM install to reload plugin cache
- Pages not displaying after creation: Check YAML frontmatter syntax in Markdown files for parsing errors
- Slow performance on large sites: Enable Grav caching in system.yaml and consider Redis cache plugin
- Theme changes not appearing: Clear Grav cache through Admin panel or delete /config/cache directory
- GPM install failing with network errors: Verify container has internet access and GPM repository is accessible

