Skip to content

[v4] Dev docs: cron jobs #463

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Parent: [v4] next-3 release
merged 4 commits into from
Nov 2, 2021
Merged

[v4] Dev docs: cron jobs #463

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2464ef6
Move CRON tasks out of functions docs & refactor structure
pwizla Oct 28, 2021
289e79c
Update: is → should be in prereq.
pwizla Oct 28, 2021
ca13d22
Update docs/developer-docs/latest/setup-deployment-guides/configurati…
pwizla Nov 2, 2021
7442725
Update docs/developer-docs/latest/setup-deployment-guides/configurati…
pwizla Nov 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/.vuepress/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'],
Expand Down
1 change: 1 addition & 0 deletions docs/developer-docs/latest/setup-deployment-guides/configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
98 changes: 98 additions & 0 deletions ...veloper-docs/latest/setup-deployment-guides/configurations/optional/cronjobs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
title: Cron jobs - Strapi Developer Documentation
description: …
---

<!-- TODO: update SEO -->

# 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',
},
},
};
```
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alexandrebodin :
@derrickmehaffy and I don't really understand this structure:

  // 'myJob': {
  //   task: ({ strapi }) => { /* Add your own logic here */ },
  //   options: {
  //     rule: '* * * * * *',
  //     end: new Date().getTime() + 6000,
  //   }
  // }

Do I also need to explain/document it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Me either

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is this example coming from ?
It's a way to set some custom options. In your example it runs the task every second but stops after 6 seconds of starting. Here is the link to the doc https://github.com/node-schedule/node-schedule#set-starttime-and-endtime

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Alex. It's coming from Strapi's own repo (examples/getstarted)


## 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,
},
});
```
62 changes: 0 additions & 62 deletions ...eloper-docs/latest/setup-deployment-guides/configurations/optional/functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
},
},
};
```
3 changes: 2 additions & 1 deletion ...developer-docs/latest/setup-deployment-guides/configurations/required/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down