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, for the whole site: see install with rsync
• Git for the code and rsync for the content, for projects under version control: see Grav with Git and rsync
• SFTP, for a one-off upload
• Git only, when nobody edits 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 sets the root path, the deployment settings and the ENV vars, see Grav configuration.

# 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.

# 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.