Grav install guide

# Versions and PHP

Grav 2.0 is the current release and needs PHP 8.3 or newer, so set the PHP version accordingly. Grav 1.7 still receives updates and runs up to PHP 8.3. The software chooser offers both majors when creating an app.

# Choose a deployment workflow

Grav writes to its own files while it runs. Pages, user accounts, uploads, and generated caches all change on the environment, so anything the CMS writes has to stay out of the deploy package:

• rsync — recommended, works for the whole site
• git for the code plus rsync for the content — for projects under version control
• SFTP — a one-off upload
• git only — when nothing is edited through the admin panel on the environment

# Get ready

Have a local PHP development environment running, with PHP 8.3 or newer and Composer for Grav 2.

# Create an app at fortrabbit

Create a new app in the fortrabbit dashboard and pick Grav as software. The software template behind the preset sets the root path, the deployment settings and the environment variables described below, so there is less to configure afterwards.

# Install with rsync

1. Download the "Grav Core + Admin plugin" package from the Grav website↗ and unpack it locally.
2. Sync the contents of the local grav-admin folder (not the folder itself) to the environment. An empty target lands in the web root:

# from inside the unpacked grav-admin folder
$ rsync -av ./ {{app-env-id}}@ssh.{{region}}.frbit.app:

3. Create the first admin account over SSH:

$ php bin/plugin login new-user -u USERNAME -e EMAIL -P b

The -P b flag grants access to both the site and the admin panel. Without a command line account, the guided web installation asks for the same details on first visit.

See the rsync article for syncing changes up and down later on.

# Deploy code with git and content with rsync

This is the more advanced route: the code lives in a git repo, the content stays on the environment. See the git deployment intro for connecting a repo.

Keep everything Grav writes out of the repo. Add these rules to .gitignore in the project root:

# .gitignore

# Composer, installed by the build command
/vendor

# Written by Grav at runtime
/cache
/logs
/tmp
/backup
/images
/assets

# Owned by the environment, synced with rsync
/user/pages
/user/accounts
/user/data
/user/config

The software template preconfigures the matching deployment settings when Grav is chosen as software: the replace strategy with the same paths as exclude patterns, a composer install build command, and a post-deploy command that recreates the empty runtime folders:

$ mkdir -p logs tmp backup images assets user/pages user/accounts user/data user/config

Grav refuses to boot when one of those folders is missing, and none of them are in the repo.

Content moves with rsync, in both directions:

# SYNC UP: local pages to the environment
$ rsync -av ./user/pages/ {{app-env-id}}@ssh.{{region}}.frbit.app:user/pages/

# SYNC DOWN: pages edited in the admin panel back to the local project
$ rsync -av {{app-env-id}}@ssh.{{region}}.frbit.app:user/pages/ ./user/pages/

Seed user/config the same way on first setup. After that it belongs to the environment.

# Configuration through environment variables

Grav 2 reads a .env file at the project root and accepts configuration overrides from real environment variables, which suits fortrabbit environment variables. Set GRAV_CONFIG to switch the feature on, then map any config path to a variable name by replacing the dots with double underscores:

GRAV_CONFIG=true
GRAV_CONFIG__system__cache__enabled=true
GRAV_CONFIG__plugins__email__mailer__smtp__password=secret

The software preset sets two of these already. GRAV_CONFIG is on, and GRAV_CONFIG__system__errors__display is 0, because the shipped user/config/system.yaml turns full backtraces on and that file is not replaced by deployments.

Server-set variables win over anything in a .env file, so secrets belong in the dashboard rather than in the repo. The shipped .env.example documents the remaining options, including the GRAV_CONFIG_ALIAS__ prefix for plugin slugs containing a hyphen.

# Environment configuration by domain

Grav also reads configuration per domain↗. For a site under development locally, debugging is usually wanted there and unwanted on fortrabbit. Create a system.yaml for the custom domain — for www.my-grav.tld that is user/www.my-grav.tld/config/system.yaml:

debugger:
  enabled: false

The stricter approach sets user/config/system.yaml as restrictive as possible and keeps a localhost override in user/localhost/config/system.yaml:

debugger:
  enabled: true

# Upgrade from Grav 1.x to 2.x

bin/gpm selfupgrade does not cross the major boundary. A 1.7 installation keeps receiving 1.7 releases and reports that 2.0 is available without installing it. Follow the Grav 2 migration guide↗, and update all plugins and themes to their latest compatible versions before the core.

Take a backup first, and raise the PHP version to 8.3 or newer if the environment still runs an older one.