mirror of
https://code.mensbeam.com/MensBeam/Arsse.git
synced 2024-12-22 13:12:41 +00:00
Significant edits to the manual
This commit is contained in:
J. King
parent
de55290746
commit
11fc83da60
15 changed files with 121 additions and 124 deletions
|
|
@ -256,7 +256,7 @@ class RoboFile extends \Robo\Tasks {
|
|||
}
|
||||
// start a task collection and create a temporary directory
|
||||
$t = $this->collectionBuilder();
|
||||
$dir = $t->workDir("/home/jking/temp").\DIRECTORY_SEPARATOR;
|
||||
$dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
|
||||
$base = $dir."arsse-$version".\DIRECTORY_SEPARATOR;
|
||||
// start by extracting the tarball
|
||||
$t->addCode(function() use ($tarball, $dir, $base) {
|
||||
|
|
@ -268,7 +268,7 @@ class RoboFile extends \Robo\Tasks {
|
|||
$t->addTask($this->taskPack($dir."arsse_$version.orig.tar.gz")->addDir("arsse-$version", $base));
|
||||
// copy Debian files to lower down in the tree
|
||||
$t->addTask($this->taskFilesystemStack()->mirror($base."dist/debian", $base."debian"));
|
||||
//$t->addTask($this->taskExec("deber")->dir($dir));
|
||||
$t->addTask($this->taskExec("deber")->dir($dir));
|
||||
return $t->run();
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,16 +0,0 @@
|
|||
The Arsse has the following requirements:
|
||||
|
||||
- A Linux server running Nginx or Apache 2.4
|
||||
- PHP 7.1.0 or later with the following extensions:
|
||||
- [intl](http://php.net/manual/en/book.intl.php), [json](http://php.net/manual/en/book.json.php), [hash](http://php.net/manual/en/book.hash.php), and [dom](http://php.net/manual/en/book.dom.php)
|
||||
- [simplexml](http://php.net/manual/en/book.simplexml.php), and [iconv](http://php.net/manual/en/book.iconv.php)
|
||||
- One of:
|
||||
- [sqlite3](http://php.net/manual/en/book.sqlite3.php) or [pdo_sqlite](http://php.net/manual/en/ref.pdo-sqlite.php) for SQLite databases
|
||||
- [pgsql](http://php.net/manual/en/book.pgsql.php) or [pdo_pgsql](http://php.net/manual/en/ref.pdo-pgsql.php) for PostgreSQL 10 or later databases
|
||||
- [mysqli](http://php.net/manual/en/book.mysqli.php) or [pdo_mysql](http://php.net/manual/en/ref.pdo-mysql.php) for MySQL/Percona 8.0.11 or later databases
|
||||
- [curl](http://php.net/manual/en/book.curl.php) (optional)
|
||||
- Privileges either to create and run systemd services, or to run cron jobs
|
||||
|
||||
Instructions for how to satisfy the PHP extension requirements for Debian and Arch Linux systems are included in the next section.
|
||||
|
||||
It is also be possible to run The Arsse on other operating systems (including Windows) and with other Web servers, but the configuration required to do so is not documented in this manual.
|
||||
|
|
@ -22,7 +22,7 @@ sudo systemctl restart php-fpm arsse
|
|||
|
||||
Note that the above is the most concise process, not necessarily the recommended one. In particular [it is recommended](https://wiki.archlinux.org/title/PHP#Extensions) to use `/etc/php/conf.d/` to enable PHP extensions rather than editing `php.ini` as done above.
|
||||
|
||||
The PHP extensions listed in [the requirements](/en/Getting_Started/Requirements) not mentioned above are compiled into Arch's PHP binaries and thus always enabled.
|
||||
The PHP extensions listed in [the requirements](/en/Getting_Started/index) not mentioned above are compiled into Arch's PHP binaries and thus always enabled.
|
||||
|
||||
# Web server configuration
|
||||
|
||||
|
|
@ -35,3 +35,13 @@ If using a database other than SQLite, you will likely want to [set it up](/en/G
|
|||
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 `/etc/webapps/arsse/` or consult [the documentation for the configuration file](/en/Getting_Started/Configuration), though The Arsse should function with the default configuration.
|
||||
|
||||
# Upgrading
|
||||
|
||||
Upgrading The Arsse is done as like any other package. By default The Arsse will perform any required database schema upgrades when the new version is executed, so the service does need to be restarted:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart arsse
|
||||
```
|
||||
|
||||
Occasionally changes to Web server configuration have been required, such as when new protocols become supported; these changes are always explicit in the `UPGRADING` file.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Installation from source code is also possible, but the release packages are rec
|
|||
|
||||
# Installation
|
||||
|
||||
In order for The Arsse to function correctly, its requirements must first be satisfied. The following series of commands should do so:
|
||||
Presently installing The Arsse on Debian systems is a manual process. The first step is to install its dependencies:
|
||||
|
||||
```sh
|
||||
# Install PHP; this assumes the FastCGI process manager will be used
|
||||
|
|
@ -19,20 +19,39 @@ sudo apt install php-intl php-json php-xml php-curl
|
|||
sudo apt install php-sqlite3 php-pgsql php-mysql
|
||||
```
|
||||
|
||||
Then, it's a simple matter of unpacking the archive someplace (`/usr/share/arsse` is the recommended location on Debian systems, but it can be anywhere) and setting permissions:
|
||||
Next its files must be unpacked into their requisite locations:
|
||||
|
||||
```sh
|
||||
# Unpack the archive
|
||||
sudo tar -xzf arsse-x.x.x.tar.gz -C "/usr/share"
|
||||
# Make the user running the Web server the owner of the files
|
||||
sudo chown -R www-data:www-data "/usr/share/arsse"
|
||||
# Ensure the owner can create files such as the SQLite database
|
||||
sudo chmod o+rwX "/usr/share/arsse"
|
||||
# Create necessary directories
|
||||
sudo mkdir -p /etc/arsse /etc/sysusers.d /etc/tmpfiles.d
|
||||
# Find the PHP version
|
||||
php_ver=`phpquery -V`
|
||||
# Move configuration files to their proper locations
|
||||
cd /usr/share/arsse/dist
|
||||
sudo mv systemd/* /etc/systemd/system/
|
||||
sudo mv sysusers.conf /etc/sysusers.d/arsse.conf
|
||||
sudo mv tmpfiles.conf /etc/tmpfiles.d/arsse.conf
|
||||
sudo mv config.php nginx apache /etc/arsse/
|
||||
sudo mv php-fpm.conf /etc/php/$php_ver/fpm/pool.d/arsse.conf
|
||||
# Move the administration executable
|
||||
sudo mv arsse /usr/bin/
|
||||
```
|
||||
|
||||
Finally, services must be restarted to apply the new configurations, and The Arsse's service also started:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart systemd-sysusers
|
||||
sudo systemctl restart systemd-tmpfiles
|
||||
sudo systemctl restart php$php_ver-fpm
|
||||
sudo systemctl reenable arsse
|
||||
sudo systemctl restart arsse
|
||||
```
|
||||
|
||||
# Web server configuration
|
||||
|
||||
Sample configuration for both Nginx and Apache HTTPd can be found in `dist/nginx/` and `dist/apache/`, respectively. The `example.conf` files are basic virtual host examples; the other files they include should normally be usable without modification, but may be modified if desired.
|
||||
Sample configuration for both Nginx and Apache HTTPd can be found in `/etc/arsse/nginx/` and `/etc/arsse/apache/`, respectively. The `example.conf` files are basic virtual host examples; the other files they include should normally be usable without modification, but may be modified if desired.
|
||||
|
||||
In order to use Apache HTTPd the FastCGI proxy module must be enabled and the server restarted:
|
||||
|
||||
|
|
@ -43,7 +62,6 @@ sudo systemctl restart apache2
|
|||
|
||||
No additional set-up is required for Nginx.
|
||||
|
||||
|
||||
# Next steps
|
||||
|
||||
If using a database other than SQLite, you will likely want to [set it up](/en/Getting_Started/Database_Setup) before doing anything else.
|
||||
|
|
@ -52,4 +70,14 @@ In order for The Arsse to serve users, those users [must be created](/en/Using_T
|
|||
|
||||
You may also want to review the `config.defaults.php` file included in the download package and create [a configuration file](/en/Getting_Started/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.
|
||||
# Upgrading
|
||||
|
||||
Upgrading The Arsse is simple:
|
||||
|
||||
1. Download the latest release
|
||||
2. Check the `UPGRADING` file for any special notes
|
||||
3. Stop the newsfeed refreshing service if it is running
|
||||
4. Install the new version per the process above
|
||||
6. Start the newsfeed refreshing service
|
||||
|
||||
By default The Arsse will perform any required database schema upgrades when the new version is executed. Occasionally changes to Web server configuration have been required, such as when new protocols become supported; these changes are always explicit in the `UPGRADING` file.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<dt>Minimum version</dt>
|
||||
<dd>3.8.3</dd>
|
||||
<dt>Configuration</dt>
|
||||
<dd><a href="../Configuration.html#page_Database-settings">General</a>, <a href="../Configuration.html#page_Database-settings-specific-to-SQLite-3">Specific</a></dd>
|
||||
<dd><a href="../Configuration.html#page_Database_settings">General</a>, <a href="../Configuration.html#page_Database_settings_specific_to_SQLite_3">Specific</a></dd>
|
||||
</dl>
|
||||
|
||||
SQLite requires very little set-up. By default the database will be created at the root of The Arsse's program directory (e.g. `/usr/share/arsse/arsse.db`), but this can be changed with the [`dbSQLite3File` setting](/en/Getting_Started/Configuration#page_dbSQLite3File).
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<dt>Minimum version</dt>
|
||||
<dd>10</dd>
|
||||
<dt>Configuration</dt>
|
||||
<dd><a href="../Configuration.html#page_Database-settings">General</a>, <a href="../Configuration.html#page_Database-settings-specific-to-PostgreSQL">Specific</a></dd>
|
||||
<dd><a href="../Configuration.html#page_Database_settings">General</a>, <a href="../Configuration.html#page_Database_settings_specific_to_PostgreSQL">Specific</a></dd>
|
||||
</dl>
|
||||
|
||||
If for whatever reason an SQLite database does not suit your configuration, PostgreSQL is the best alternative. It is functionally equivalent to SQLite in every way.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
<dt>Minimum version</dt>
|
||||
<dd>8.0.11</dd>
|
||||
<dt>Configuration</dt>
|
||||
<dd><a href="../Configuration.html#page_Database-settings">General</a>, <a href="../Configuration.html#page_Database-settings-specific-to-MySQL">Specific</a></dd>
|
||||
<dd><a href="../Configuration.html#page_Database_settings">General</a>, <a href="../Configuration.html#page_Database_settings_specific_to_MySQL">Specific</a></dd>
|
||||
</dl>
|
||||
|
||||
While MySQL can be used as a database for The Arsse, this is **not recommended** due to MySQL's technical limitations. It is fully functional, but may fail with some newsfeeds where other database systems do not. Additionally, it is particularly important before upgrading from one version of The Arsse to the next to back up your database: a failure in a database upgrade can corrupt your database much more easily than when using other database systems.
|
||||
|
|
|
|||
|
|
@ -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 "[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.
|
||||
Consult "[How Often Newsfeeds Are Fetched](/en/Using_The_Arsse/Other_Topics#page_How_often_newsfeeds_are_fetched)" for details on newsfeed update frequency.
|
||||
|
||||
### serviceQueueWidth
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,20 @@
|
|||
Presently installing and setting up The Arsse is a manual process. We hope to have pre-configured installation packages available for various operating systems eventually, but for now the pages in this section should help get you up and running.
|
||||
Presently installing and setting up The Arsse involves some manual labour. We have packages for Arch Linux and hope to have installation packages available for other operating systems eventually, but for now the pages in this section should help get you up and running on Arch Linux or Debian-based systems, with Nginx or Apache HTTPd.
|
||||
|
||||
Though The Arsse itself makes no assumptions about the operating system which hosts it, we use and have the most experience with Debian; the instructions contained here therefore are for Debian systems and will probably either not work with other systems or not be consistent with their conventions. Nevertheless, they should still serve as a useful guide.
|
||||
It is also be possible to run The Arsse on other operating systems (including Windows) and with other Web servers, but the configuration required to do so is not documented in this manual.
|
||||
|
||||
# Requirements
|
||||
|
||||
For reference, The Arsse has the following requirements:
|
||||
|
||||
- A Linux server running Nginx or Apache 2.4
|
||||
- PHP 7.1.0 or later with the following extensions:
|
||||
- [intl](http://php.net/manual/en/book.intl.php), [json](http://php.net/manual/en/book.json.php), [hash](http://php.net/manual/en/book.hash.php), and [dom](http://php.net/manual/en/book.dom.php)
|
||||
- [simplexml](http://php.net/manual/en/book.simplexml.php), and [iconv](http://php.net/manual/en/book.iconv.php)
|
||||
- One of:
|
||||
- [sqlite3](http://php.net/manual/en/book.sqlite3.php) or [pdo_sqlite](http://php.net/manual/en/ref.pdo-sqlite.php) for SQLite databases
|
||||
- [pgsql](http://php.net/manual/en/book.pgsql.php) or [pdo_pgsql](http://php.net/manual/en/ref.pdo-pgsql.php) for PostgreSQL 10 or later databases
|
||||
- [mysqli](http://php.net/manual/en/book.mysqli.php) or [pdo_mysql](http://php.net/manual/en/ref.pdo-mysql.php) for MySQL/Percona 8.0.11 or later databases
|
||||
- [curl](http://php.net/manual/en/book.curl.php) (optional)
|
||||
- Privileges either to create and run systemd services, or to run cron jobs
|
||||
|
||||
Instructions for how to satisfy the PHP extension requirements for Arch Linux and Debian systems are included in the next section.
|
||||
|
|
|
|||
|
|
@ -9,13 +9,13 @@ This section describes in brief some CLI commands. Please read [the general note
|
|||
When first installed, The Arsse has no users configured. You may add users by executing the following command:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user add "user@example.com" "example password"
|
||||
sudo arsse user add "user@example.com" "example password"
|
||||
```
|
||||
|
||||
The password argument is optional: if no password is provided, a random one is generated and printed out:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php user add "jane.doe"
|
||||
$ sudo arsse user add "jane.doe"
|
||||
Ji0ivMYqi6gKxQK1MHuE
|
||||
```
|
||||
|
||||
|
|
@ -24,13 +24,13 @@ Ji0ivMYqi6gKxQK1MHuE
|
|||
Setting a user's password is nearly identical to adding a user:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user set-pass "user@example.com" "new password"
|
||||
sudo arsse user set-pass "user@example.com" "new password"
|
||||
```
|
||||
|
||||
As when adding a user, the password argument is optional: if no password is provided, a random one is generated and printed out:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php user set-pass "jane.doe"
|
||||
$ sudo arsse user set-pass "jane.doe"
|
||||
Ummn173XjbJT4J3Gnx0a
|
||||
```
|
||||
|
||||
|
|
@ -39,13 +39,13 @@ Ummn173XjbJT4J3Gnx0a
|
|||
Before a user can make use of [the Fever protocol](/en/Supported_Protocols/Fever), a Fever-specific password for that user must be set. It is _highly recommended_ that this not be the samer as the user's main password. The password can be set by adding the `--fever` option to the normal password-changing command:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user set-pass --fever "user@example.com" "fever password"
|
||||
sudo arsse user set-pass --fever "user@example.com" "fever password"
|
||||
```
|
||||
|
||||
As when setting a main password, the password argument is optional: if no password is provided, a random one is generated and printed out:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php user set-pass --fever "jane.doe"
|
||||
$ sudo arsse user set-pass --fever "jane.doe"
|
||||
YfZJHq4fNTRUKDYhzQdR
|
||||
```
|
||||
|
||||
|
|
@ -54,16 +54,16 @@ YfZJHq4fNTRUKDYhzQdR
|
|||
[Miniflux](/en/Supported_Protocols/Miniflux) clients may optionally log in using tokens: randomly-generated strings which act as persistent passwords. For now these must be generated using the command-line interface:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php token create "jane.doe"
|
||||
$ sudo arsse token create "jane.doe"
|
||||
xRK0huUE9KHNHf_x_H8JG0oRDo4t_WV44whBtr8Ckf0=
|
||||
```
|
||||
|
||||
Multiple tokens may be generated for use with different clients, and descriptive labels can be assigned for later identification:
|
||||
|
||||
```console
|
||||
$ sudo -u www-data php arsse.php token create "jane.doe" Newsflash
|
||||
$ sudo arsse token create "jane.doe" Newsflash
|
||||
xRK0huUE9KHNHf_x_H8JG0oRDo4t_WV44whBtr8Ckf0=
|
||||
$ sudo -u www-data php arsse.php token create "jane.doe" Reminiflux
|
||||
$ sudo arsse token create "jane.doe" Reminiflux
|
||||
L7asI2X_d-krinGJd1GsiRdFm2o06ZUlgD22H913hK4=
|
||||
```
|
||||
|
||||
|
|
@ -76,13 +76,13 @@ Users may also have various metadata properties set. These largely exist for com
|
|||
The flag may be changed using the following command:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user set "jane.doe" admin true
|
||||
sudo arsse user set "jane.doe" admin true
|
||||
```
|
||||
|
||||
As a shortcut it is also possible to create administrators directly:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php user add "user@example.com" "example password" --admin
|
||||
sudo arsse user add "user@example.com" "example password" --admin
|
||||
```
|
||||
|
||||
Please consult the integrated help for more details on metadata and their effects.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ This section describes in brief some CLI commands. Please read [the general note
|
|||
It's possible to import not only newsfeeds but also folders and Fever groups using OPML files. The process is simple:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php import "user@example.com" "subscriptions.opml"
|
||||
sudo arsse import "user@example.com" "subscriptions.opml"
|
||||
```
|
||||
|
||||
The importer is forgiving, but some OPML files may fail, with the reason printed out. Files are either imported in total, or not at all.
|
||||
|
|
@ -19,7 +19,7 @@ The importer is forgiving, but some OPML files may fail, with the reason printed
|
|||
It's possible to export not only newsfeeds but also folders and Fever groups to OPML files. The process is simple:
|
||||
|
||||
```sh
|
||||
sudo -u www-data php arsse.php export "user@example.com" "subscriptions.opml"
|
||||
sudo arsse export "user@example.com" "subscriptions.opml"
|
||||
```
|
||||
|
||||
The output might look like this:
|
||||
|
|
@ -46,9 +46,9 @@ Not all protocols supported by The Arsse allow modifying newsfeeds or folders, e
|
|||
|
||||
```sh
|
||||
# export your newsfeeds
|
||||
sudo -u www-data php arsse.php export "user@example.com" "subscriptions.opml"
|
||||
sudo arsse export "user@example.com" "subscriptions.opml"
|
||||
# make any changes you want in your editor of choice
|
||||
nano "subscriptions.opml"
|
||||
# re-import the modified information
|
||||
sudo -u www-data php arsse.php import "user@example.com" "subscriptions.opml" --replace
|
||||
sudo arsse import "user@example.com" "subscriptions.opml" --replace
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,49 +0,0 @@
|
|||
[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 systemd 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:
|
||||
|
||||
```
|
||||
*/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 change frequently are checked frequently, and those which change seldom are fetched at most daily.
|
||||
30
docs/en/025_Using_The_Arsse/030_Other_Topics.md
Normal file
30
docs/en/025_Using_The_Arsse/030_Other_Topics.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
[TOC]
|
||||
|
||||
# Refreshing newsfeeds with a cron job
|
||||
|
||||
Normally The Arsse has a systemd service which checks newsfeeds for updates and processes them into its database for the user. If for whatever reason this is not practical a [cron](https://en.wikipedia.org/wiki/Cron) job may be used instead.
|
||||
|
||||
Keeping newsfeeds updated with cron is not difficult. Simply run the following command:
|
||||
|
||||
|
||||
```sh
|
||||
sudo crontab -u arsse -e
|
||||
```
|
||||
|
||||
And add a line such as this one:
|
||||
|
||||
```
|
||||
*/2 * * * * /usr/bin/arsse 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.
|
||||
|
||||
# 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 change frequently are checked frequently, and those which change seldom are fetched at most daily.
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
Upgrading The Arsse is usually simple:
|
||||
|
||||
1. Download the latest release
|
||||
2. Check the `UPGRADING` file for any special notes
|
||||
3. Stop the newsfeed refreshing service if it is running
|
||||
4. Extract the new version on top of the old one
|
||||
5. Ensure permissions are still correct
|
||||
6. Restart the newsfeed refreshing service
|
||||
|
||||
By default The Arsse will perform any required database schema upgrades when the new version is executed, and release packages contain all newly required library dependencies.
|
||||
|
||||
Occasionally changes to Web server configuration have been required, when new protocols become supported; such changes are always explicit in the `UPGRADING` file
|
||||
|
|
@ -2,19 +2,8 @@
|
|||
|
||||
This section details a few administrative tasks which may need to be performed after installing The Arsse. As no Web-based administrative interface is included, these tasks are generally performed via command line interface.
|
||||
|
||||
Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed with the CLI itself by executing `php arsse.php --help`.
|
||||
Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed with the CLI itself by executing `arsse --help`.
|
||||
|
||||
# A Note on Command Invocation
|
||||
|
||||
Particularly if using an SQLite database, it's important that administrative commands be executed as the same user who owns The Arsse's files. To that end the examples in this section all use the verbose formulation `sudo -u www-data php arsse.php` (with `www-data` being the user under which Web servers run in Debian), but it is possible to simplify invocation to `sudo arsse` if an executable file named `arsse` is created somewhere in the sudo path with the following content:
|
||||
|
||||
```php
|
||||
#! /usr/bin/env php
|
||||
<?php
|
||||
if (posix_geteuid() == 0) {
|
||||
$info = posix_getpwnam("www-data");
|
||||
posix_setegid($info['gid']);
|
||||
posix_seteuid($info['uid']);
|
||||
}
|
||||
include "/usr/share/arsse/arsse.php";
|
||||
```
|
||||
Particularly if using an SQLite database, it's important that administrative commands be executed as the same user who owns The Arsse's files. To that end our releases include an `arsse` executable which drops privileges when executed as root. Commands in this section assume this executable is being used.
|
||||
|
|
|
|||
Loading…
Reference in a new issue