Grav Configuration & Caching — Production Performance Tuning

In this tutorial, you'll learn how to configure Grav for production — from caching to security settings.

What You'll Learn

• Grav's configuration system and file hierarchy
• Enabling and tuning caching for maximum performance
• Twig compilation and template optimization
• Asset pipeline (CSS/JS minification)
• Production security settings

Why It Matters

Grav's default settings are optimized for development — they prioritize flexibility over speed. In production, the opposite is true. Without proper caching, every page request compiles Twig from scratch, reads Markdown files, and processes content. With caching, a page load takes milliseconds instead of seconds.

Real-World Use

A documentation site with 2,000 pages: without caching, each request takes ~400ms. With file caching enabled, Twig compiled, and the asset pipeline active, response times drop to ~30ms. For a site getting 50,000 daily visitors, that's the difference between a $10 server and a $100 server.

Configuration Files

Grav's configuration lives in user/config/. The two most important files:

user/config/
├── system.yaml        # Core Grav settings
├── site.yaml          # Site-specific settings
├── security.yaml      # Security configuration
├── themes/            # Per-theme config
│   └── quark.yaml
└── plugins/           # Per-plugin config
    ├── admin.yaml
    ├── form.yaml
    └── email.yaml

Settings cascade: Default → System → Site → Theme → Plugin → Page frontmatter. Each level overrides the previous.

System.YAML Reference

Key settings in system.yaml:

# ── Basic setup ──
home:
    alias: /home                     # Default page (folder name)
    hide_in_urls: false              # Hide "home" from /

# ── Caching ──
cache:
    enabled: true                    # Enable caching
    check:
        method: file                 # File change detection
    driver: auto                     # auto, file, redis, memcached
    prefix: grav
    lifetime: 604800                 # Cache lifetime in seconds (7 days)
    gzip: true                       # Compress cached pages

# ── Twig ──
twig:
    cache: true                      # Cache compiled Twig templates
    debug: false                     # Disable in production
    auto_reload: false               # Disable in production
    autoescape: true                 # Prevent XSS

# ── Assets ──
assets:
    css_pipeline: true               # Combine CSS files
    css_minify: true                 # Minify CSS
    js_pipeline: true                # Combine JS files
    js_minify: true                  # Minify JS

# ── Performance ──
pages:
    markdown:
        extra: true                  # Enable Markdown Extra
    process: true                    # Process Twig in page content
    events:
        page: true
    build_cache: false               # Enable for large sites

Caching Backends

File Cache (Default)

Stores cached pages and compiled Twig as files in user/data/cache/.

Pros: No additional setup, works everywhere. Cons: Slower than memory-based caches.

cache:
    enabled: true
    driver: file

Redis Cache

Stores cache in memory via Redis.

Pros: Fast, shared across multiple servers. Cons: Requires Redis server and PHP Redis extension.

cache:
    enabled: true
    driver: redis
    redis:
        socket: /var/run/redis/redis.sock
        server: localhost
        port: 6379
        password: ''                  # Set if Redis requires auth

Memcached Cache

Uses Memcached for object caching.

cache:
    enabled: true
    driver: memcached
    memcached:
        server: localhost
        port: 11211

Twig Optimization

Twig is Grav's template engine. Optimize it for production:

twig:
    cache: true                      # Cache compiled Twig templates
    debug: false                     # Debug info slows rendering
    auto_reload: false               # Don't check template file mtime
    autoescape: true                 # Escape output by default

auto_reload: false is critical in production. When true, Grav checks every template file's modification time on every request — defeating the purpose of caching.

Asset Pipeline

The asset pipeline combines and minifies CSS and JavaScript files.

assets:
    css_pipeline: true               # All CSS in one HTTP request
    css_minify: true                 # Remove whitespace, comments
    js_pipeline: true                # All JS in one HTTP request
    js_minify: true                  # Remove whitespace, comments

Without pipelining:

/styles.css              → 1 request
/custom.css              → 1 request
/fonts.css               → 1 request

With pipelining:

/asset.css?pipeline=true → 1 request (all 3 files combined)

Enable pipelining after you finish theme development — it makes debugging harder but production faster.

Production Checklist

Before going live, apply these settings:

# user/config/system.yaml — production
cache:
    enabled: true
    check:
        method: file
    driver: auto
    prefix: grav
    gzip: true

twig:
    cache: true
    debug: false
    auto_reload: false

assets:
    css_pipeline: true
    css_minify: true
    js_pipeline: true
    js_minify: true

pages:
    markdown:
        extra: false                 # Disable for security
    process: true

security:
    xss_protection: true
    content_security_policy: true
    x_frame_options: deny

Clear Development Cache

bin/grav cache --all

This clears Twig cache, page cache, and assets cache. Your site starts fresh with optimized settings.

Security Hardening

# user/config/security.yaml
security:
    xss_protection: true
    content_security_policy: true
    x_frame_options: deny
    default_same_site: lax

Additional security measures:

1. Set proper file permissions:

   find user/ -type f -exec chmod 644 {} \;
   find user/ -type d -exec chmod 755 {} \;
   chmod 755 bin/grav
   

2. Protect sensitive files: Add to .htaccess (Apache) or server config (Nginx):

   # Deny access to YAML and Twig files
   <FilesMatch "\.(yaml|twig|md)$">
       Require all denied
   </FilesMatch>
   

3. Disable admin access by IP: Restrict /admin to specific IPs in your web server config.

Performance Testing

After optimization, test your site:

# Check response time
curl -o /dev/null -s -w "%{time_total}\n" http://localhost:8000/

# Check page size with gzip
curl -H "Accept-Encoding: gzip" -o /dev/null -s -w "%{size_download}\n" http://localhost:8000/

# Check cache hit
curl -I http://localhost:8000/ | grep X-Grav-Cache

Expected results after optimization:

• Response time: < 100ms (often 20-50ms)
• Page size: 50-80% smaller with gzip
• Cache header: X-Grav-Cache: hit

Learning Path

flowchart LR
  A["What is Grav?"] --> B["Installation"]
  B --> C["Pages & Content"]
  C --> D["Navigation"]
  D --> E["Twig Templating"]
  E --> F["Themes"]
  F --> G["Taxonomy & Blog"]
  G --> H["Plugins & Admin"]
  H --> I["Configuration & Caching
← You are here"]:::current
  I --> J["Deployment & Maintenance"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Practice Questions

1. What does twig.auto_reload: false do in production? Answer: It prevents Grav from checking template modification times on every request, which significantly improves performance.

2. What three caching drivers does Grav support? Answer: File, Redis, and Memcached. File is the default and works everywhere.

3. How does the asset pipeline improve performance? Answer: It combines multiple CSS/JS files into one HTTP request and minifies them, reducing round trips and file size.

4. What happens when you clear the cache? Answer: bin/grav cache --all deletes compiled Twig templates, cached pages, and combined assets. The site rebuilds them on next request.

5. Challenge: Apply the production configuration to your Grav site. Verify cache hits in the response headers. Run a performance test before and after to measure the improvement.

What's Next

Your site is optimized. Now let's put it online:

Continue to Lesson 10: Deployment & Maintenance — Deploy Grav to a production server and keep it running.