Codakey
Play
← Back to getgrav/grav

How to Deploy & Use getgrav/grav

Grav CMS Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using Grav, a modern, flat-file CMS.

1. Prerequisites

Before installing Grav, ensure you have the following software and tools:

  • PHP: Version 7.3.6 or higher.
    • Required PHP Modules: Refer to the official Grav documentation for a complete list, which typically includes gd, curl, zip, mbstring, xml, opcache.
  • Web Server:
  • Composer (Optional, for create-project or specific dependency management): Download Composer.
  • Git (Optional, for cloning from GitHub): Download Git.

2. Installation

Grav offers several methods for installation. Choose the one that best suits your needs.

Option 1: Downloading a Grav Package (Recommended for beginners)

This is the simplest way to get started as it provides a ready-to-use Grav instance.

  1. Navigate to the official Grav downloads page: https://getgrav.org/downloads.
  2. Download the desired Grav package (e.g., "Grav Core + Admin Plugin" for a full-featured setup).
  3. Extract the downloaded ZIP archive to your web server's document root (e.g., ~/webroot/grav).
    • On Linux/macOS: unzip grav-admin-vX.Y.Z.zip -d ~/webroot/grav
    • On Windows: Use a tool like 7-Zip or the built-in extractor.
  4. Grav is now installed and ready to run.

Option 2: Using Composer

This method is ideal for developers who prefer managing dependencies with Composer.

  1. Open your terminal or command prompt.
  2. Navigate to your web server's document root (e.g., cd ~/webroot).
  3. Execute the Composer command to create a new Grav project: 
    composer create-project getgrav/grav ~/webroot/grav
    Replace ~/webroot/grav with your desired installation path.

Option 3: From GitHub (For Developers)

This method provides the latest development version and requires manual dependency installation.

  1. Open your terminal or command prompt.
  2. Navigate to your web server's document root (e.g., cd ~/webroot).
  3. Clone the Grav repository: 
    git clone https://github.com/getgrav/grav.git
  4. Navigate into the newly created Grav directory: 
    cd grav
  5. Install plugin and theme dependencies using the Grav CLI application: 
    bin/grav install

3. Configuration

Grav uses YAML files for configuration. The main configuration files are located in the user/config/ directory.

  • System Configuration: user/config/system.yaml
  • Site Configuration: user/config/site.yaml

Common Configuration Adjustments

  • Base URL: Grav automatically detects the base URL, but you can explicitly set it in user/config/system.yaml under home.base_url if needed.
  • Caching: Grav utilizes Doctrine Cache (as seen in system/src/Grav/Framework/Flex/FlexDirectory.php). Caching settings can be adjusted in user/config/system.yaml.
  • Languages: Configure supported languages in user/config/system.yaml under the languages section. Grav's Language class (from system/src/Grav/Common/Language/Language.php) handles language detection and management.
  • Admin Plugin (if installed): Access the admin panel at http://your-grav-site.com/admin to manage most configurations through a user-friendly interface. Initial setup will prompt for an admin user creation.

Environment Variables

While Grav primarily uses YAML for configuration, you can override certain settings using environment variables. This is particularly useful for production deployments.

For example, to override a system setting like cache.enabled, you might set an environment variable GRAV_CACHE_ENABLED=false. Refer to the Grav documentation for specific environment variable mappings.

4. Build & Run

Grav is a PHP application and does not require a separate "build" step in the traditional sense. Running it involves serving the PHP files through a web server.

Local Development

  1. Ensure Web Server is Running: Make sure your Apache, Nginx, or IIS server is configured to serve the Grav installation directory.
  2. Access in Browser: Open your web browser and navigate to the URL where Grav is installed (e.g., http://localhost/grav or http://grav.test).

Production

For production environments, ensure your web server is properly configured for security and performance.

  1. Web Server Configuration:
    • Apache: Ensure .htaccess files are enabled and AllowOverride All is set for the Grav directory.
    • Nginx: Configure the location / block to handle Grav's routing, typically using try_files $uri $uri/ /index.php?$query_string;.
  2. Permissions: Set appropriate file permissions for the Grav installation. The cache, logs, images, assets, and user directories usually require write permissions for the web server user. A common recommendation is chmod -R 755 . for directories and chmod -R 644 . for files, with specific write permissions for the aforementioned directories.
  3. Caching: Ensure caching is enabled and configured for optimal performance in user/config/system.yaml.
  4. Error Reporting: Disable display_errors in your php.ini and rely on logging for errors.

5. Deployment

Grav's flat-file nature makes it highly portable. Appropriate deployment platforms include:

  • Shared Hosting: Most shared hosting providers support PHP and common web servers (Apache/Nginx), making Grav an excellent fit. Simply upload the Grav files.
  • VPS/Dedicated Servers: For more control and performance, deploy Grav on a Virtual Private Server (VPS) or dedicated server. This allows for fine-tuning PHP and web server configurations.
  • Containerization (Docker): Create a Docker image for Grav, bundling PHP, Nginx/Apache, and Grav itself. This provides consistent environments across development and production.
    • Example Dockerfile (simplified): 
      FROM php:8.1-apache

# Install PHP extensions
RUN docker-php-ext-install pdo_mysql gd opcache exif mbstring zip

# Enable mod_rewrite
RUN a2enmod rewrite

# Copy Grav files
COPY . /var/www/html/

# Set permissions
RUN chown -R www-data:www-data /var/www/html/cache \
    /var/www/html/logs \
    /var/www/html/images \
    /var/www/html/assets \
    /var/www/html/user

EXPOSE 80
  • Managed Hosting (e.g., Platform.sh, Kinsta, Cloudways): These platforms often have optimized PHP environments and can simplify Grav deployments with Git integration.

Deployment Steps (General)

  1. Prepare Grav Installation: Ensure all plugins and themes are installed (bin/grav install) and configurations are set.
  2. Transfer Files:
    • FTP/SFTP: For shared hosting, upload the entire Grav directory.
    • Git Pull: On a VPS or containerized environment, clone the repository or pull updates.
    • Deployment Tools: Use tools like rsync, Capistrano, or custom deployment scripts for automated deployments.
  3. Set Permissions: Adjust file and directory permissions on the server to allow the web server to write to necessary folders (cache, logs, images, assets, user).
  4. Configure Web Server: Ensure your web server (Apache, Nginx, IIS) is correctly configured to point to Grav's root directory and handle URL rewriting.
  5. Run GPM Commands (if needed): After deployment, you might need to run bin/gpm update to update Grav, plugins, and themes.

6. Troubleshooting

  • Blank Page / 500 Error:
    • Check PHP Version: Ensure your PHP version meets the 7.3.6+ requirement.
    • PHP Error Logs: Check your web server's PHP error logs for detailed messages.
    • Permissions: Verify that Grav's cache/, logs/, images/, assets/, and user/ directories have write permissions for the web server user.
    • PHP Memory Limit: Increase memory_limit in php.ini if you encounter memory-related errors.
  • Page Not Found (404) Errors:
    • mod_rewrite (Apache): Ensure mod_rewrite is enabled in Apache and AllowOverride All is set for the Grav directory in your Apache configuration.
    • Nginx try_files: Verify your Nginx configuration includes the correct try_files directive.
    • Base URL: Check user/config/system.yaml for home.base_url if you're using a subdirectory installation.
  • Admin Panel Not Loading / Issues:
    • Clear Cache: Navigate to your Grav root and run bin/grav clear-cache.
    • Plugin Conflicts: Temporarily disable recently installed plugins by renaming their folders in user/plugins/.
  • GPM (Grav Package Manager) Issues:
    • Connectivity: Ensure your server has outbound internet access to reach getgrav.org.
    • allow_url_fopen: Check if allow_url_fopen is enabled in php.ini.
    • curl extension: Ensure the PHP curl extension is installed and enabled.
  • "Whoops!" Error Page: This is Grav's default error page. Check the logs/grav.log file for specific error details.
  • Slow Performance:
    • Caching: Ensure Grav's caching is enabled and working (user/config/system.yaml).
    • PHP Opcache: Verify opcache is enabled and configured in php.ini.
    • Image Processing: Large images without proper optimization can slow down pages. Grav's Gregwar Image Library (mentioned in the README) can help with dynamic image manipulation, but pre-optimizing images is best.

For further assistance, consult the comprehensive Grav documentation at learn.getgrav.org or join the Discord Chat Server.

← Project overviewView alternatives to getgrav/grav →