Grav Installation Guide — Local Development Setup

In this tutorial, you'll install Grav CMS on your local machine and see your first page — all without creating a single database.

What You'll Learn

• How to set up a local PHP environment
• How to download and install Grav
• The Grav folder structure and what each directory does
• How to verify your installation is working

Why It Matters

The fastest way to learn Grav is to have it running on your own machine. Installation takes under 5 minutes — no database setup, no configuration wizard, no "create a database first" step. Once it's running, you can experiment freely without affecting a live site.

Real-World Use

This is the same Process you'd use to set up a local development environment for any Grav project. Developers clone a Grav site, run bin/grav install, and start editing. The flat-file structure means your local copy is identical to production — no database syncing needed.

Prerequisites

Step-by-Step: Install Grav

Step 1: Download Grav

There are two ways to get Grav:

Option A — Composer (recommended for developers):

composer create-project getgrav/grav grav-site

Option B — Direct download:

# Download the zip
wget https://getgrav.org/download/core/grav/latest

# Or use curl
curl -L -o grav.zip https://getgrav.org/download/core/grav/latest

# Unzip
unzip grav.zip
mv grav grav-site

Both methods give you the same result: a grav-site folder with a complete Grav installation.

Step 2: Install Dependencies

cd grav-site
bin/grav install

This command:

1. Installs PHP dependencies via Composer
2. Sets up the default folder structure
3. Creates necessary symlinks and permissions

You should see output like:

Installing dependencies via Composer...
Installing Grav plugins...
Setting up permissions...
Done!

Step 3: Start the Development Server

Grav includes PHP's built-in web server:

bin/grav server

Output:

Development server started on http://localhost:8000

Open your browser and visit http://localhost:8000. You should see Grav's default home page.

flowchart LR
  A["Download Grav"] --> B["bin/grav install"]
  B --> C["bin/grav server"]
  C --> D["Visit localhost:8000"]
  D --> E["🎉 Your site is live!"]
  
  style C fill:#38bdf8,color:#0f172a
  style E fill:#10b981,color:#fff

Step 4: Explore the Folder Structure

grav-site/
├── user/
│   ├── accounts/          # User accounts (Admin plugin)
│   ├── blueprints/        # Custom form definitions
│   ├── config/            # System configuration
│   │   ├── system.yaml    # Main config
│   │   └── site.yaml      # Site-specific settings
│   ├── data/              # Cache, logs, sessions
│   ├── pages/             # Your content (Markdown files)
│   ├── plugins/           # Installed plugins
│   └── themes/            # Installed themes
├── vendor/                # Composer dependencies
├── bin/                   # CLI tools
│   ├── grav               # Main CLI
│   └── gpm                # Grav Package Manager
├── index.php              # Entry point
└── .grav/                 # Internal state

The user/ directory is where all your work happens — content, config, themes, plugins. Everything else is the Grav core and should not be modified directly.

Step 5: Customize Site Settings

Open user/config/site.yaml:

title: My Documentation Site
author:
    name: Your Name
    email: you@example.com
metadata:
    description: A developer documentation site built with Grav

Open user/config/system.yaml and set your site URL:

home:
    alias: /home
pages:
    theme: quark
    markdown:
        extra: true

Changes take effect immediately — no cache clear needed during development.

Folder Tour: Where Things Live

Common Installation Errors

Next Steps with the Admin Plugin

For a web-based editor experience, install the Admin plugin:

bin/gpm install admin

Then create an admin user:

bin/grav new-admin-user

You'll be prompted for a username, password, and email. After that, visit http://localhost:8000/admin to log in.

Learning Path

flowchart LR
  A["What is Grav?"] --> B["Installation
← You are here"]:::current
  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"]
  I --> J["Deployment & Maintenance"]

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

Practice Questions

1. What command starts Grav's development server? Answer: bin/grav server — it starts PHP's built-in web server on port 8000 by default.

2. Where do Grav content files live? Answer: In user/pages/. Each page is a folder containing a Markdown file with YAML frontmatter.

3. How do you install plugins and themes? Answer: Using the Grav Package Manager: bin/gpm install <package-name>.

4. Challenge: Change the site title in user/config/site.yaml, then visit http://localhost:8000/admin (after installing the Admin plugin) and verify the title appears in the admin dashboard.

5. What happens if port 8000 is already in use? Answer: Use a different port: bin/grav server --port=8080.

What's Next

Your Grav site is running. Let's create some pages:

Continue to Lesson 3: Pages & Content — Create your home page, about page, and understand Grav's page system.