Documentation for service and cron

docs/config.json

@@ -1,5 +1,5 @@
 {
-    "title": "The Arsse",
+    "title": "The Advanced RSS Environment",
     "tagline": "The clean & modern RSS server that doesn't give you any crap.",
     "languages": {
         "en": "English"

docs/en/020_Getting_Started/020_Download_and_Installation.md

@@ -32,23 +32,12 @@ sudo chown -R www-data:www-data "/usr/share/arsse"
 sudo chmod o+rwX "/usr/share/arsse"
 ```
 
-Finally, The Arsse's newsfeed refreshing service needs to be installed in order for news to actually be fetched from the Internet:
-
-```sh
-# Copy the service unit
-sudo cp "/usr/share/arsse/dist/arsse.service" "/etc/systemd/system"
-# Modify the unit file if needed
-sudoedit "/etc/systemd/system/arsse.service"
-# Enable and start the service
-sudo systemctl enable --now arsse.service
-```
-
-If using a database other than SQLite, you will likely want to [set it up](Database_Setup) before setting up the service.
-
-It's also possible to instead use a cron job to schedule newsfeed checks, but using the systemd service when possible is recommended.
-
 # Next Steps
 
-In order for the various synchronization protocols to work, a Web server [must be configured](Web_Server_Configuration), and in order for The Arsse to serve users, those users [must be created](/en/Using_The_Arsse/Managing_Users). The following manual pages provide details on how to get this set up.
+If using a database other than SQLite, you will likely want to [set it up](Database_Setup) before doing anything else.
+
+In order for the various synchronization protocols to work, a Web server [must be configured](Web_Server_Configuration), and in order for The Arsse to serve users, those users [must be created](/en/Using_The_Arsse/Managing_Users).
 
 You may also want to review the `config.defaults.php` file included in the download package and create [a configuration file](Configuration), though The Arsse can function even without using a configuration file.
+
+Finally, The Arsse's [newsfeed refreshing service](/en/Using_The_Arsse/Keeping_Newsfeeds_Up_to_Date) needs to be installed in order for news to actually be fetched from the Internet.

docs/en/020_Getting_Started/050_Configuration.md

@@ -321,7 +321,7 @@ It is also possible to specify the fully-qualified name of a class which impleme
 
 The interval the newsfeed fetching service observes between checks for new articles. Note that requests to foreign servers are not necessarily made at this frequency: each newsfeed is assigned its own time at which to be next retrieved. This setting instead defines the length of time the fetching service will sleep between periods of activity.
 
-Consult "[Newsfeed Refresh Schedule](/en/Installation/Using_the_Daemon#page_Newsfeed_Refresh_Schedule)" for details on how often newsfeeds are fetched.
+Consult "[How Often Newsfeeds Are Fetched](/en/Using_The_Arsse/Keeping_Newsfeeds_Up_to_Date#page_Appendix-How-Often-Newsfeeds-Are-Fetched)" for details on how often newsfeeds are fetched.
 
 ### serviceQueueWidth
 

docs/en/025_Using_The_Arsse/030_Keeping_Newsfeeds_Up_to_Date.md

@@ -0,0 +1,49 @@
+[TOC]
+
+# Preface
+
+In normal operation The Arsse is expected to regularly check whether newsfeeds might have new articles, then fetch them and process them to present new or updated articles to clients. This can be achieved either by having The Arsse operate a persistent background process (termed a [daemon](https://en.wikipedia.org/wiki/Daemon_(computing)) or service), or by using an external scheduler to periodically perform single checks. Normally a daemon is preferred.
+
+There are many ways to administer daemons, and many schedulers can be used. This section outlines a few, but many other arrangements are possible.
+
+# As a Daemon via Systemd
+
+The Arsse includes a sample system service unit file which can be used to quickly get a daemon running with the following procedure:
+
+```sh
+# Copy the service unit
+sudo cp "/usr/share/arsse/dist/arsse.service" "/etc/systemd/system"
+# Modify the unit file if needed
+sudoedit "/etc/systemd/system/arsse.service"
+# Enable and start the service
+sudo systemctl enable --now arsse
+```
+
+The Arsse's feed updater can then be manipulated as with any other service. Consult [the `systemctl` manual](https://www.freedesktop.org/software/systemd/man/systemctl.html) for details.
+
+# As a Cron Job
+
+Keeping newsfeeds updated with [cron](https://en.wikipedia.org/wiki/Cron) is not difficult. Simply run the following command:
+
+
+```sh
+sudo crontab -u www-data -e
+```
+
+And add a line such as this one:
+
+```cron
+*/2 * * * * /usr/bin/env php /usr/share/arsse/arsse.php refresh-all
+```
+
+Thereafter The Arsse's will be scheduled to check newsfeeds every two minutes. Consult the manual pages for the `crontab` [format](http://man7.org/linux/man-pages/man5/crontab.5.html) and [command](http://man7.org/linux/man-pages/man1/crontab.1.html) for details.
+
+# Appendix: How Often Newsfeeds Are Fetched
+
+Though by default The Arsse will wake up every two minutes, newsfeeds are not actually downloaded so frequently. Instead, each newsfeed is assigned a time at which it should next be fetched, and once that time is reached a [conditional request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests) is made. The interval between requests for a particular newsfeed can vary from 15 minutes to 24 hours based on multiple factors such as:
+
+- The length of time since the newsfeed last changed
+- The interval between publishing of articles in the newsfeed
+- Whether the last fetch or last several fetches resulted in error
+
+As a general rule, newsfeeds which changed frequently are checked frequently, and those which change seldom are fetched at most daily.