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..a1faa35573 --- /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 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. + +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/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("./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` |