From 2464ef6c231e05ffcb72ed0633ae677f9e4a8775 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 28 Oct 2021 12:37:19 +0200 Subject: [PATCH 1/4] Move CRON tasks out of functions docs & refactor structure --- docs/.vuepress/config.js | 1 + .../setup-deployment-guides/configurations.md | 1 + .../configurations/optional/cronjobs.md | 98 +++++++++++++++++++ .../configurations/optional/functions.md | 62 ------------ .../configurations/required/server.md | 3 +- 5 files changed, 102 insertions(+), 63 deletions(-) create mode 100644 docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 1ff86049fc..8ba5336d87 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -58,6 +58,7 @@ const sidebar = { children: [ ['/developer-docs/latest/setup-deployment-guides/configurations/optional/middlewares.md', 'Middlewares'], ['/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md', 'Functions'], + ['/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md', 'Cron jobs'], ['/developer-docs/latest/setup-deployment-guides/configurations/optional/api.md', 'API'], ['/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md', 'Plugins'], ['/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md', 'Environment'], diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations.md b/docs/developer-docs/latest/setup-deployment-guides/configurations.md index bd02eeec91..8bc546efa0 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations.md @@ -63,6 +63,7 @@ Strapi also offers the following optional configuration options for specific fea - [middlewares](/developer-docs/latest/setup-deployment-guides/configurations/optional/middlewares.md) - [functions](/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md) +- [cron jobs](/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md) - [API calls](/developer-docs/latest/setup-deployment-guides/configurations/optional/api.md) - [plugins](/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md) - the [environment and its variables](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md new file mode 100644 index 0000000000..bc5338703f --- /dev/null +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md @@ -0,0 +1,98 @@ +--- +title: Cron jobs - Strapi Developer Documentation +description: … +--- + + + +# Cron jobs + +:::prerequisites +The `cron.enabled` configuration option is set to `true` in [the `./config/server.js` file](/developer-docs/latest/setup-deployment-guides/configurations/required/server.md). +::: + +`cron` allows scheduling arbitrary functions for execution at specific dates, with optional recurrence rules. These functions are named cron jobs. `cron` only uses a single timer at any given time, rather than reevaluating upcoming jobs every second/minute. + +This feature is powered by the [`node-schedule`](https://www.npmjs.com/package/node-schedule) package. + +The `cron` format consists of: + +``` + +* * * * * * +┬ ┬ ┬ ┬ ┬ ┬ +│ │ │ │ │ | +│ │ │ │ │ └ day of week (0 - 7) (0 or 7 is Sun) +│ │ │ │ └───── month (1 - 12) +│ │ │ └────────── day of month (1 - 31) +│ │ └─────────────── hour (0 - 23) +│ └──────────────────── minute (0 - 59) +└───────────────────────── second (0 - 59, OPTIONAL) + +``` + +To define cron jobs and have them run at the required times: + +1. [Create](#creating-a-cron-job) the appropriate file. +2. [Enable](#enabling-cron-jobs) the cron jobs in the server configuration file. + +::: tip +Optionally, cron jobs can be directly created in the `cron.tasks` key of the [server configuration file](/developer-docs/latest/setup-deployment-guides/configurations/required/server.md). +::: + +## Creating a cron job + +To define a cron job, create a file with the following structure: + +```js +// path: ./config/src/cron-tasks.js + +module.exports = { + /** + * Simple example. + * Every monday at 1am. + */ + + '0 0 1 * * 1': ({ strapi }) => { + // Add your own logic here (e.g. send a queue of email, create a database backup, etc.). + }, +}; +``` + +If the cron job is required to run based on a specific timezone, configure it like the following: + +```js +module.exports = { + /** + * Cron job with timezone example. + * Every Monday at 1am for Asia/Dhaka timezone. + * List of valid timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List + */ + + '0 0 1 * * 1': { + task: ({ strapi }) => { /* Add your own logic here */ }, + options: { + tz: 'Asia/Dhaka', + }, + }, +}; +``` + +## Enabling cron jobs + +To enable cron jobs, set `cron.enabled` to `true` in the [server configuration file](/developer-docs/latest/setup-deployment-guides/configurations/required/server.md) and declare the jobs: + +```js +// path: ./config/server.js + +const cronTasks = require("./src/cron-tasks"); + +module.exports = ({ env }) => ({ + host: env("HOST", "0.0.0.0"), + port: env.int("PORT", 1337), + cron: { + enabled: true, + tasks: cronTasks, + }, +}); +``` diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md index 73537b19c9..866e69e091 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md @@ -58,65 +58,3 @@ module.exports = async () => { await someSetup(); }; ``` - -## CRON tasks - -CRON tasks allow you to schedule jobs (arbitrary functions) for execution at specific dates, with optional recurrence rules. It only uses a single timer at any given time (rather than reevaluating upcoming jobs every second/minute). - -This feature is powered by the [`node-schedule`](https://www.npmjs.com/package/node-schedule) package. - -:::caution -Make sure the `enabled` cron config is set to `true` in `./config/server.js` file. -::: - -The cron format consists of: - -``` -* * * * * * -┬ ┬ ┬ ┬ ┬ ┬ -│ │ │ │ │ | -│ │ │ │ │ └ day of week (0 - 7) (0 or 7 is Sun) -│ │ │ │ └───── month (1 - 12) -│ │ │ └────────── day of month (1 - 31) -│ │ └─────────────── hour (0 - 23) -│ └──────────────────── minute (0 - 59) -└───────────────────────── second (0 - 59, OPTIONAL) -``` - -To define a CRON job, add your logic like below: - -```js -// path: ./config/functions/cron.js - -module.exports = { - /** - * Simple example. - * Every monday at 1am. - */ - - '0 0 1 * * 1': () => { - // Add your own logic here (e.g. send a queue of email, create a database backup, etc.). - }, -}; -``` - -If your CRON task is required to run based on a specific timezone then you can configure the task like below: - -```js -module.exports = { - /** - * CRON task with timezone example. - * Every monday at 1am for Asia/Dhaka timezone. - * List of valid timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List - */ - - '0 0 1 * * 1': { - task: () => { - // Add your own logic here (e.g. send a queue of email, create a database backup, etc.). - }, - options: { - tz: 'Asia/Dhaka', - }, - }, -}; -``` diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md index 64dea8758b..e6c3e91c32 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/server.md @@ -98,7 +98,8 @@ module.exports = ({ env }) => ({ | `url` | Public url of the server. Required for many different features (ex: reset password, third login providers etc.). Also enables proxy support such as Apache or Nginx, example: `https://mywebsite.com/api`. The url can be relative, if so, it is used with `http://${host}:${port}` as the base url. An absolute url is however **recommended**. | string | `''` | | `proxy` | Set the koa variable `app.proxy`. When `true`, proxy header fields will be trusted. | boolean | `false` | | `cron` | Cron configuration (powered by [`node-schedule`](https://github.com/node-schedule/node-schedule)) | Object | | -| `cron.enabled` | Enable or disable CRON tasks to schedule jobs at specific dates. | boolean | `false` | +| `cron.enabled` | Enable or disable [CRON jobs](/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md) to schedule jobs at specific dates. | boolean | `false` | +| `cron.tasks` | Declare [CRON jobs](/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md) to be run at specific dates. | boolean | `false` | | `admin` | Admin panel configuration | Object | | | `admin.auth` | Authentication configuration | Object | | | `admin.auth.secret` | Secret used to encode JWT tokens | string | `undefined` | From 289e79c9efbd97fad081179ccac3e7642fe0da46 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Thu, 28 Oct 2021 16:10:56 +0200 Subject: [PATCH 2/4] =?UTF-8?q?Update:=20is=20=E2=86=92=20=20should=20be?= =?UTF-8?q?=20in=20prereq.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../setup-deployment-guides/configurations/optional/cronjobs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md index bc5338703f..3001f33cc7 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md @@ -8,7 +8,7 @@ description: … # Cron jobs :::prerequisites -The `cron.enabled` configuration option is set to `true` in [the `./config/server.js` file](/developer-docs/latest/setup-deployment-guides/configurations/required/server.md). +The `cron.enabled` configuration option should be set to `true` in [the `./config/server.js` file](/developer-docs/latest/setup-deployment-guides/configurations/required/server.md). ::: `cron` allows scheduling arbitrary functions for execution at specific dates, with optional recurrence rules. These functions are named cron jobs. `cron` only uses a single timer at any given time, rather than reevaluating upcoming jobs every second/minute. From ca13d22370cdfac659dd4d1d4c9821099b5b47cc Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 2 Nov 2021 16:11:06 +0100 Subject: [PATCH 3/4] Update docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md Co-authored-by: DMehaffy --- .../setup-deployment-guides/configurations/optional/cronjobs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md index 3001f33cc7..88f32147af 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md @@ -85,7 +85,7 @@ To enable cron jobs, set `cron.enabled` to `true` in the [server configuration f ```js // path: ./config/server.js -const cronTasks = require("./src/cron-tasks"); +const cronTasks = require("./cron-tasks"); module.exports = ({ env }) => ({ host: env("HOST", "0.0.0.0"), From 7442725ff5cd9fb20a23f6c0b888dbac5c050286 Mon Sep 17 00:00:00 2001 From: Pierre Wizla Date: Tue, 2 Nov 2021 16:11:12 +0100 Subject: [PATCH 4/4] Update docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md Co-authored-by: DMehaffy --- .../setup-deployment-guides/configurations/optional/cronjobs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md index 88f32147af..a1faa35573 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md @@ -45,7 +45,7 @@ Optionally, cron jobs can be directly created in the `cron.tasks` key of the [se To define a cron job, create a file with the following structure: ```js -// path: ./config/src/cron-tasks.js +// path: ./config/cron-tasks.js module.exports = { /**