15 changed files with 121 additions and 124 deletions
@ -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. |
|||
@ -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. |
|||
|
|||
@ -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. |
|||
@ -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 |
|||
Loading…
Reference in new issue