It turns out Grav has excellent command-line tools for managing the installation. Grav’s Command Line Interface (CLI) offers the website’s administrator exceptional versatility to upgrade, update plugins, clean cache, or even create a theme from scratch. Sometimes shared web hosting providers provide SSH access to your account, and Grav comes ready for it with scripts on the bin/ directory.

We highly recommend using the CLI for such maintenance tasks, as these come without the restrictions your web hosting could impose over scripts running too long via the web browser. It often could happen that you were updating your Grav installation over the Admin plugin and your web host interrupted the script execution because of a timeout. These timeouts could result in unfinished upgrades that most likely will cause problems and error messages down the line, or at worst, an incomplete upgrade that remains vulnerable from a web security standpoint.

Enter: Ansible

Ansible is a configuration management solution that enables the website administrator to automate system administration tasks. Since Grav includes a well-designed CLI, Ansible can also use it to keep your Grav installation in good standing. If you have many Grav installations, define these as hosts in the Inventory file we have provided.

Ansible Playbooks are organized tasks in a file that act as a recipe of steps to be executed. We’ve created a playbook that runs 3 specific functions:

  • Upgrades Grav installation
  • Updates plugins
  • Clears cache

This playbook lives in the ansible-grav repository, which you can clone from our GitHub account.

After cloning it, you’ll have to set up your SSH credentials in the inventory file we’ve provided. Use the same hostname (host1, host2, etc.) as the same ansible_user you’re using, as many cPanel-based web hosts structure their webserver directories as /home/<your-username>/public_html. For example, if our SSH username was frthemes, our inventory file should look like this:

          ansible_host: <ip-address-here>
          ansible_port: <ssh-port-here>
          ansible_user: frthemes
          ansible_password: <ssh-password-here>
          ansible_ssh_extra_args: -o StrictHostKeyChecking=no

There’s no need to enclose the values in quotes or the angle brackets we’ve just used in the previous example. Save the file and keep note of the name, as you’ll reference this file as part of the -i parameter of the ansible-playbook command.

This inventory change reflects in our playbook as:

- name: Grav self-upgrade and update plugins
  hosts: webservers
    grav_full_path: /home/frthemes/public_html


You do not need to change the playbook; it has a variable that automatically calls the inventory_hostname value as part of the path unless your Grav installation directory differs from this structure, which is standard for cPanel installations.

For running the playbook, you can use the command ansible-playbook. In our example, we used it like this:

[frthemes@server ansible-grav]$ ansible-playbook -i inventory.yaml grav-upgrade.yaml

You may want to automate this command with a weekly cron job, but not before enabling regular backups in case of an update that takes down your website.

Until next time,

Blog Logo

Ivan Montilla Miralles



Frontier Themes

Back to Overview