Rework crontab usage

docs/administration/recent_activity/recent_activity.md

@@ -31,11 +31,10 @@
                 truncate_after_days: 15
 ```
 
-To automate a regular truncation, the command `ibexa:activity-log:truncate` must be added to a crontab.
+To automate a regular truncation, the command `ibexa:activity-log:truncate` must be added to a cron job.
 To minimize the number of entries to delete, it's recommended to execute the command more than one time a day.
 
-For every exact hour, the cronjob line is:
-`0 * * * * cd [path-to-ibexa]; php bin/console ibexa:activity-log:truncate --quiet --env=prod`
+For more information, see [Additional cron jobs and advanced usage](install_ibexa_dxp.md#additional-cron-jobs-and-advanced-usage).
 
 ### Display limit
 

docs/cdp/cdp_data_export_schedule.md

@@ -40,7 +40,7 @@
 Under the `schedule` setting you can find separate sections for exporting user, content, and product.
 Structure of each section is exactly the same and includes `interval` and `options` elements:
 
-- `interval` - sets the frequency of the command invoke, for example, '*/30 * * * *' means "every 30 minutes", '0 */12 * * *' means "every 12th hour".
+- `interval` - sets the frequency of the command invoke, for example, `'*/30 * * * *'` means "every 30 minutes", `'0 */12 * * *'` means "every 12th hour".
 It uses a standard `crontab` format, see [examples](https://crontab.guru/examples.html).
 - `options`- allows you to add arguments that have to be passed to the export command.
 
@@ -66,3 +66,7 @@
 ```bash
 php bin/console ibexa:cdp:stream-content-data --help
 ```
+
+The configuration is executed by `ibexa:cron:run` command which must be configured as a cron job.
+
+For more information, see [Scheduling tasks](install_ibexa_dxp.md#schedule-tasks).

docs/content_management/url_management/url_management.md

@@ -37,24 +37,7 @@ The following protocols are currently supported:
 
 To enable automatic URL validation, set up cron to run the `ibexa:check-urls` command periodically.
 
-For example, to check links every week, add the following script:
-
-```bash
-echo '0 0 * * 0 cd [path-to-ibexa]; php bin/console ibexa:check-urls --quiet --env=prod' > ezp_cron.txt
-```
-
-Next, append the new cron to user's crontab without destroying existing crons.
-Assuming that the web server user data is www-data:
-
-```bash
-crontab -u www-data -l|cat - ezp_cron.txt | crontab -u www-data -
-```
-
-Finally, remove the temporary file:
-
-```bash
-rm ezp_cron.txt
-```
+For more information, see [Additional cron jobs and advanced usage](install_ibexa_dxp.md#additional-cron-jobs-and-advanced-usage).
 
 ### Configuration
 

docs/discounts/configure_discounts.md

@@ -49,12 +49,14 @@ To run discount re-indexing in the background:
 php bin/console messenger:consume ibexa.messenger.transport --bus=ibexa.messenger.bus
 ```
 
-3\. Use a scheduler of your choice, for example, [cron](https://en.wikipedia.org/wiki/Cron), to periodically run the following command:
+3\. Periodically run the following command, about one time a day or more often:
 
 ``` bash
 php bin/console ibexa:discounts:reindex
 ```
 
+For more information about scheduling a command, see [Additional cron jobs and advanced usage](install_ibexa_dxp.md#additional-cron-jobs-and-advanced-usage).
+
 !!! note "Deploying Symfony Messenger"
 
     For more information about deploying the Messenger to production, see [Symfony documentation]([[= symfony_doc =]]/messenger.html#deploying-to-production).

docs/getting_started/install_ibexa_dxp.md

@@ -1,5 +1,6 @@
 ---
 description: Install Ibexa DXP on a Linux system and prepare your installation for production.
+month_change: true
 ---
 
 # Install Ibexa DXP
@@ -395,7 +396,6 @@
 
     You can use [this example vhost file](https://raw.githubusercontent.com/ibexa/post-install/main/resources/templates/nginx/vhost.template) and modify it to fit your project. You also need the `ibexa_params.d` files that should reside in a subdirectory below where the main file is, [as is shown here](https://github.com/ibexa/post-install/tree/5.0/resources/templates/nginx).
 
-
     Specify `/<your installation directory>/public` as the `root`, or ensure `BASEDIR` is set in the environment.
     Ensure `APP_ENV` is set to `prod` or `dev` in the environment, depending on the environment that you're configuring, and uncomment the line that starts with `#if[APP_ENV`.
 
@@ -412,34 +412,122 @@
 
     See the [Security checklist](security_checklist.md) for a list of security-related issues you should take care of before going live with a project.
 
-### Enable Date-based Publisher
+### Schedule tasks
+
+The `ibexa:cron:run` command executes all service commands tagged `ibexa.cron.job`.
+It should be scheduled to run every minute using [`cron`](https://en.wikipedia.org/wiki/Cron).
+
+The following example creates a temporary file with the crontab entry and appends it to the existing crontab for the web server user (`www-data`):
+
+```bash
+echo '* * * * * cd <path-to-ibexa-dxp>; php bin/console ibexa:cron:run --quiet --env=prod' > ibexa_cron.txt
+crontab -u www-data -l | cat - ibexa_cron.txt | crontab -u www-data -
+rm ibexa_cron.txt
+```
+
+For [Scheduled content publications]([[= user_doc =]]/content_management/schedule_publishing/), the `ibexa:scheduled:run` command is tagged with `ibexa.cron.job` and, by default, runs every minute (`* * * * *`).
+If needed, you can redefine this service to set up another frequency.
+
+The [CDP data export schedule](cdp_data_export_schedule.md) dynamically creates services tagged with `ibexa.cron.job`.
+
+You can add other commands to cron by either:
 
-To enable delayed publishing of Content using the Date-based Publisher, you must set up cron to run the `bin/console ibexa:scheduled:run` command periodically.
+- Adding their own scheduling line to the crontab
+- Tagging their service with `ibexa.cron.job`
 
-For example, to check for publishing every minute, add the following script:
+#### Additional cron jobs and advanced usage
 
-`echo '* * * * * cd [path-to-ibexa-dxp]; php bin/console ibexa:cron:run --quiet --env=prod' > ezp_cron.txt`
+To use [Link manager](url_management.md), schedule the URL validation command `ibexa:check-urls`.
+
+To [control the recent activity log size](recent_activity.md#log-retention), schedule the `ibexa:activity-log:truncate` command.
+
+To [re-index discounts](discounts_guide.md#discount-re-indexing), schedule the `ibexa:discounts:reindex` command (after having set Ibexa Messenger, for more information, see [Discount re-indexing configuration](configure_discounts.md#discount-re-indexing)).
+
+The following example schedules these commands separately:
+
+- `ibexa:cron:run` [every minute](https://crontab.guru/every-minute)
+- `ibexa:check-urls` [every week](https://crontab.guru/weekly) (on Sunday at midnight)
+- `ibexa:activity-log:truncate` [every hour](https://crontab.guru/every-hour) (at minute 0)
+- `ibexa:discounts:reindex` [every day](https://crontab.guru/every-day) (at midnight)
+
+This shell script creates a temporary file with the job lines, then replaces the existing crontab for the web server user:
+
+```bash
+echo '* * * * * cd <path-to-ibexa-dxp>; php bin/console ibexa:cron:run --quiet --env=prod' > ibexa_cron.txt
+echo '0 0 * * 0 cd <path-to-ibexa-dxp>; php bin/console ibexa:check-urls --quiet --env=prod' >> ibexa_cron.txt
+echo '0 * * * * cd <path-to-ibexa-dxp>; php bin/console ibexa:activity-log:truncate --quiet --env=prod' >> ibexa_cron.txt
+echo '0 0 * * * cd <path-to-ibexa-dxp>; php bin/console ibexa:discounts:reindex --quiet --env=prod' >> ibexa_cron.txt
+crontab -u www-data ibexa_cron.txt
+rm ibexa_cron.txt
+```
 
-For 5-minute intervals:
+The following alternative example uses service tagging to schedule these commands.
+It also changes the `ibexa:scheduled:run` frequency to every five minutes.
 
-`echo '*/5 * * * * cd [path-to-ibexa-dxp]; php bin/console ibexa:cron:run --quiet --env=prod' > ezp_cron.txt`
+Add the following to `config/services.yaml`:
 
-Next, append the new cron to user's crontab without destroying existing crons.
-Assuming the web server user data is `www-data`:
+```yaml
+services:
+    #…
 
-`crontab -u www-data -l|cat - ezp_cron.txt | crontab -u www-data -`
+    Ibexa\Bundle\Scheduler\Command\ScheduledRunCommand:
+        tags:
+            - { name: ibexa.cron.job, schedule: '*/5 * * * *' }
 
-Finally, remove the temporary file:
+    Ibexa\Bundle\Core\Command\CheckURLsCommand:
+        arguments:
+            $urlChecker: '@Ibexa\Bundle\Core\URLChecker\URLChecker'
+        tags:
+            - { name: ibexa.cron.job, schedule: '0 0 * * 0', priority: -1 }
 
-`rm ezp_cron.txt`
+    Ibexa\Bundle\ActivityLog\Command\TruncateLogCommand:
+      tags:
+        - { name: ibexa.cron.job, schedule: '0 * * * *', priority: -2 }
+
+    Ibexa\Bundle\Discounts\Command\ReIndexDiscountProductCommand:
+      tags:
+        - { name: ibexa.cron.job, schedule: '0 0 * * *' }
+```
+
+The `ibexa.cron.job` tag accepts the following options:
+
+- `schedule`: A cron expression representing the period or interval.
+- `options`: Arguments passed to the command. Note that `--env` and `--siteaccess` are inherited from `ibexa:cron:run`.
+- `category`: Commands can be grouped into categories, and a category can be passed with `ibexa:cron:run --category=<CATEGORY>`. By default, the `default` category is used.
+  For example, it can be used to set different jobs and `schedule` for different [SiteAccesses](multisite_configuration.md).
+- `priority`: Defines the order in which `ibexa:cron:run` executes commands that are due.
+
+You can list the command services schedule by this tag with the following command:
+
+```bash
+php bin/console debug:container --tag=ibexa.cron.job
+```
+
+The following example shows how to set up a different schedule for a specific SiteAccess with a category.
+
+This command schedules `ibexa:cron:run` for the SiteAccess `minor_website` and the job category `minor_website`:
+
+```bash
+(crontab -u www-data -l; echo '* * * * * cd <path-to-ibexa-dxp>; php bin/console ibexa:cron:run --quiet --env=prod --siteaccess=minor_website --category=minor_website') | crontab -u www-data -
+```
+
+Then, `ibexa:scheduled:run` can run on this SiteAccess at a different frequency from the default:
+
+```yaml
+    Ibexa\Bundle\Scheduler\Command\ScheduledRunCommand:
+        tags:
+            - { name: ibexa.cron.job, schedule: '* * * * *' }
+            - { name: ibexa.cron.job, schedule: '*/5 * * * *', category: 'minor_website' }
+```
 
-### Enable the Link manager
+### Enable background tasks
 
-To make use of the [Link Manager](url_management.md#enabling-automatic-url-validation).
+Enable Ibexa Messenger for background tasks, make sure that its [worker starts with the server](background_tasks.md#start-worker).
 
-### Enable discount re-indexing [[% include 'snippets/commerce_badge.md' %]]
+Ibexa Messenger is used at least by:
 
-Enable [discount re-indexing in the background](configure_discounts.md#discount-re-indexing).
+- CDP data export, see [Ibexa Messenger support for large batches of data](cdp_data_export.md#ibexa-messenger-support-for-large-batches-of-data)
+- [Discount re-indexing](configure_discounts.md#discount-re-indexing)
 
 ## [[= product_name_cloud =]]