GRAV Schedule Setup Instructions

Setting up the scheduler for GRAV is, by our definition, standard operating procedure when deploying this CMS. This feature automates backups, clears, and purges cache your application nightly.

This feature is built into the GRAV core and configured via the Admin Plugin or CLI. We find that the second option, CLI, is the most stable for setting up and will walk you through the configuration process.

What is the GRAV Scheduler?

The Grav scheduler is a feature introduced in early versions 1.6 GRAV Core. The idea of the feature is to run jobs on a schedule. The idea is that you only need to run one CRON job to multiple tasks. You create an entry in the scheduler and runs at a designated time; however, you do not need to add each entry as a separate CRON task.

GRAV States
One of the main advantages of utilizing the scheduler to handle tasks is that they can be performed without any user interaction and independently of the front end. Tasks such as periodic cache clearing, backups, synchronization, search indexing, etc., are all prime candidates for scheduled jobs.
Source: https://learn.getgrav.org/16/advanced/scheduler

What are the system Jobs Includeded?

There are typically 3 jobs included in the GRAV Core:

cache-purge
This task clears out cache files that have expired.

cache-clear
The cache clear works the same way as the bin/grav clear command.

default-site-backup
The default backup job available via the Grav Backup configuration.

How to activate GRAV Scheduler

As we mentioned before we would prefer to set up the schedule via CLI. To start this process you need to log in via SSH

Step 1 - Login via SSH

Step 2 - Check the status of your Scheduler

If your GRAV installation was designed, developed, or managed by a web designer or firm, it is a good idea to check the current status of the schedule.

Complete this by using the following command:

[user@host grav_main_direcotry]$ php bin/grav scheduler -i

The output of this command will give you one of two responses:

The Scheduler is not setup:

Install Scheduler
=================

 [ERROR] Can't find a crontab for [user]. You need to set up Grav's Scheduler in your crontab                       

 ! [NOTE] To install, run the following command from your terminal:                                                     

 (crontab -l; echo "* * * * * cd /route/to/your/main/directory;/route/to/your/php/version/running/in/cli bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

The Scheduler is setup:

 Install Scheduler
=================

 [OK] All Ready! You have already set up Grav's Scheduler in your crontab. You can validate this by running "crontab -l"
      to list your current crontab entries.                                                                             

 ! [NOTE] To reinstall, run the following command from your terminal:                                                   

(crontab -l; echo "* * * * * cd /route/to/your/main/directory;/route/to/your/php/version/running/in/cli bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

If you received a response as "is not setup" continue the next step to continue the setup process.

Step 3 - Add the CRON task via CLI

The GRAV system, as usual, gives you a simple way to add this task to your CRON schedule without actually having to access the server's control panel. This approach is helpful as there are many panels available. The instructions to reach each CRON schedule would be time-consuming to display.

Instead, we are going to use the data directly from the response of the command bin/grav scheduler -i

Look at the response below:

[user@host grav_main_direcotry]$ php bin/grav scheduler -i

Install Scheduler
=================

 [ERROR] Can't find a crontab for [user]. You need to set up Grav's Scheduler in your crontab                       

 ! [NOTE] To install, run the following command from your terminal:                                                     

 (crontab -l; echo "* * * * * cd /route/to/your/main/directory;/route/to/your/php/version/running/in/cli bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

You will see the statement ! [NOTE] To install, run the following command from your terminal:

This is then followed with a CLI command (crontab -l; echo "* * * * * cd /route/to/your/main/directory;/route/to/your/php/version/running/in/cli bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

Copy the command, paste it and press enter. This will automatically add the CRON job to your existing CRON Schedule.

Step 4 - Has the CRON been added

Run the command bin/grav scheduler -i and your response should now say that:

 [OK] All Ready! You have already set up Grav's Scheduler in your crontab. You can validate this by running "crontab -l"
      to list your current crontab entries.  

Step 5 - Activate the Jobs you would like to Automate

The final step we will take is to decide which tasks we would like to automate.

To select the tasks (already existing) you would like to activate you need to navigate to {grav_root}/user/config/ and edit the scheduler.yaml file, shown below:

[user]@[hostname]:~/public_html$ cd user/config/
[user]@[hostname]:~/public_html/user/config$ vi scheduler.yaml

The edit the scheduler.yaml file

status:
  cache-purge: enabled
  cache-clear: enabled
  default-site-backup: enabled
~
~
~
~

Change disabled to enabled for the tasks you would like to automate.

To save your changes

~
~
:w

You will receive a response

~
~
~
"scheduler.yaml" 4L, 85C written

Then exit the file:

~
~
~
:wq

Check your configuration

It is a good idea to check your configuration by using the command bin/grav scheduler -j

[user@host grav_main_direcotry]$ php bin/grav scheduler -j

Scheduler Jobs Listing
======================

┌─────────────────────┬────────────────────────────────────┬───────────┬────────┬──────────┬─────────┐
│ Job ID              │ Command                            │ Run At    │ Status │ Last Run │ State   │
├─────────────────────┼────────────────────────────────────┼───────────┼────────┼──────────┼─────────┤
│ cache-purge         │ Grav\Common\Cache::purgeJob        │ 0 4 * * * │ Ready  │ Never    │ Enabled │
│ cache-clear         │ Grav\Common\Cache::clearJob        │ 0 3 * * * │ Ready  │ Never    │ Enabled │
│ default-site-backup │ Grav\Common\Backup\Backups::backup │ 0 3 * * * │ Ready  │ Never    │ Enabled │
└─────────────────────┴────────────────────────────────────┴───────────┴────────┴──────────┴─────────┘

 ! [NOTE] For error details run "bin/grav scheduler -d" 

If the scheduler is not working properly

If your scheduler is not working properly, you can use the command bin/grav scheduler -d the response to this command could reveal detailed errors.

[user@host grav_main_direcotry]$ php bin/grav scheduler -j

Job Details
===========

┌─────────────────────┬──────────┬──────────────────┬────────┐
│ Job ID              │ Last Run │ Next Run         │ Errors │
├─────────────────────┼──────────┼──────────────────┼────────┤
│ default-site-backup │ Never    │ 2021-06-12 03:00 │ None   │
│ cache-purge         │ Never    │ 2021-06-12 04:00 │ None   │
│ cache-clear         │ Never    │ 2021-06-12 03:00 │ None   │
└─────────────────────┴──────────┴──────────────────┴────────┘

What else does the scheduler do

So now you have your scheduler setup. You can create custom jobs to automate an additional task or even run commands for third-party plugins. The options are endless, and you well on your way to unleashing the full potential of a GRAV CMS.

Of course, if you need help with your online web presence, we are here to help. We hope we have saved you some time!