diff --git a/docs/en/020_Getting_Started/020_Download_and_Installation/010_On_Arch_Linux.md b/docs/en/020_Getting_Started/020_Download_and_Installation/010_On_Arch_Linux.md index c1560432..e075c1b2 100644 --- a/docs/en/020_Getting_Started/020_Download_and_Installation/010_On_Arch_Linux.md +++ b/docs/en/020_Getting_Started/020_Download_and_Installation/010_On_Arch_Linux.md @@ -14,7 +14,7 @@ For illustrative purposes, this document assumes the `yay` [AUR helper](https:// # Install the package sudo yay -S arsse # Enable the necessary PHP extensions; curl is optional but recommended; pdo_sqlite may be used instead of sqlite3, but this is not recommended -sudo sed -ie 's/^;\(extension=\(curl\|iconv\|intl\|sqlite3\)\)$/\1/' /etc/php/php.ini +sudo sed -i -e 's/^;\(extension=\(curl\|iconv\|intl\|sqlite3\)\)$/\1/' /etc/php/php.ini # Enable and start the necessary systemd units sudo systemctl enable php-fpm arsse sudo systemctl restart php-fpm arsse @@ -22,8 +22,6 @@ 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/index) not mentioned above are compiled into Arch's PHP binaries and thus always enabled. - # Web server configuration Sample configuration for both Nginx and Apache HTTP Server can be found in `/etc/webapps/arsse/nginx/` and `/etc/webapps/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. diff --git a/docs/en/020_Getting_Started/020_Download_and_Installation/999_ On_Other_Systems.md b/docs/en/020_Getting_Started/020_Download_and_Installation/999_ On_Other_Systems.md new file mode 100644 index 00000000..a496aa04 --- /dev/null +++ b/docs/en/020_Getting_Started/020_Download_and_Installation/999_ On_Other_Systems.md @@ -0,0 +1,53 @@ +# Downloading The Arsse + +The Arsse should run on any operating system for which PHP and a Web server are available, but only the combination of Linux, Systemd, Nginx, and PHP-FPM has been extensively tested. + +Below are very generic instructions and suggestions for installing The Arsse on systems for which pre-built packages are not available. + +# Requirements + +The Arsse has the following requirements: + +- A Web server such as: + - [Nginx](https://nginx.org) + - [Apache HTTP server](https://httpd.apache.org) 2.4 or later +- PHP 7.1.0 or later with the following extensions: + - [intl](https://php.net/manual/en/book.intl.php), [json](https://php.net/manual/en/book.json.php), [hash](https://php.net/manual/en/book.hash.php), [filter](https://php.net/manual/en/book.filter.php), and [dom](https://php.net/manual/en/book.dom.php) + - [simplexml](https://php.net/manual/en/book.simplexml.php), and [iconv](https://php.net/manual/en/book.iconv.php) + - One of: + - [sqlite3](https://php.net/manual/en/book.sqlite3.php) or [pdo_sqlite](https://php.net/manual/en/ref.pdo-sqlite.php) for SQLite databases + - [pgsql](https://php.net/manual/en/book.pgsql.php) or [pdo_pgsql](https://php.net/manual/en/ref.pdo-pgsql.php) for PostgreSQL 10 or later databases + - [mysqli](https://php.net/manual/en/book.mysqli.php) or [pdo_mysql](https://php.net/manual/en/ref.pdo-mysql.php) for MySQL/Percona 8.0.11 or later databases + - [curl](https://php.net/manual/en/book.curl.php) (optional) + - [posix](https://php.net/manual/en/book.posix.php) and [pcntl](https://php.net/manual/en/book.pcntl.php) (both optional) +- An interface between PHP and the Web server, such as [PHP-FPM](https://php.net/manual/en/install.fpm.php) +- Privileges either to create and run system services, or to run cron jobs + +# Installation + +1. Download [the latest release](https://thearsse.com/releases/current) and extract it somewhere, such as `/usr/share/arsse/` +2. [Set up your database](/en/Getting_Started/Database_Setup) +3. Create [a configuration file](/en/Getting_Started/Configuration) if needed +4. Consult the files under `dist/nginx` and `dist/apache` for sample Web server configuration +5. Consult `dist/arsse` for a sample executable script which drops privileges on POSIX systems +6. Start the newsfeed fetching service: + - Sample Systemd service files are available under `dist/systemd` + - A sample System V init script is available in `dist/init.sh` + - A persistent process can be started by running `php arsse.php daemon` + - It is also possible [to use cron](/en/Using_The_Arsse/Other_Topics.html#page_Refreshing_newsfeeds_with_a_cron_job) or a similar task-scheduling tool +7. [Create users](/en/Using_The_Arsse/Managing_Users) to grant them access + +# Upgrading + +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. Back up your configurationm and database +5. Extract the new version on top of the old one +6. Restart 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, when new protocols become supported; such changes are always explicit in the `UPGRADING` file diff --git a/docs/en/020_Getting_Started/020_Download_and_Installation/index.md b/docs/en/020_Getting_Started/020_Download_and_Installation/index.md new file mode 100644 index 00000000..4ad7b147 --- /dev/null +++ b/docs/en/020_Getting_Started/020_Download_and_Installation/index.md @@ -0,0 +1,16 @@ +# Installing from a package manager + +We currently provide a few pre-built installation packages for the following operating systems: + +- [Arch Linux and derivatives](On_Arch_Linux) +- [Debian and derivatives](On_Debian_and_Derivatives) + +These packages significantly simplify installation, though a bit of manual effort may still be required. Updating The Arsse using these packages should require no manual intervention. + +# Installing manually + +For other systems The Arsse must currently be installed manually. As each operating system is different, we can only provide very general instructions: + +- [Installing on other systems](On_Other_Systems) + +We hope to support more operating systems in the future. diff --git a/docs/en/020_Getting_Started/040_Database_Setup/000_SQLite.md b/docs/en/020_Getting_Started/040_Database_Setup/000_SQLite.md index 1aa5992c..10c505fc 100644 --- a/docs/en/020_Getting_Started/040_Database_Setup/000_SQLite.md +++ b/docs/en/020_Getting_Started/040_Database_Setup/000_SQLite.md @@ -11,6 +11,14 @@
General, Specific
-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). +SQLite requires very little set-up. By default the database will be created at one of the following locations depending on installation method: -Regardless of the location chosen, The Arsse **must** be able to both read from and write to the database file, as well as create files in its directory. This is because SQLite also creates a write-ahead log file and a shared-memory file during operation. +| Installation method | Default database path | +|---------------------|------------------------------------------------------| +| Arch Linux package | `/var/lib/arsse/arsse.db` | +| Debian package | `/var/lib/dbconfig-common/sqlite3/arsse/arsse` | +| Manual installation | `arsse.db` in the The Arsse's installation directory | + +This path can be changed with the [`dbSQLite3File` setting](/en/Getting_Started/Configuration#page_dbSQLite3File). + +Regardless of the location used, The Arsse **must** be able to both read from and write to the database file, as well as create files in its directory. This is because SQLite also creates a write-ahead log file and a shared-memory file during operation. diff --git a/docs/en/020_Getting_Started/050_Configuration.md b/docs/en/020_Getting_Started/050_Configuration.md index f93a2a7c..561ce065 100644 --- a/docs/en/020_Getting_Started/050_Configuration.md +++ b/docs/en/020_Getting_Started/050_Configuration.md @@ -1,6 +1,14 @@ # The configuration file -The Arsse looks for configuration in a file named `config.php` in the directory where it is installed. For example, if The Arsse is installed at `/usr/share/arsse`, it will look for configuration in the file `/usr/share/arsse/config.php`. It is not an error for this file not to exist or to be empty: The Arsse will function with no configuration whatsoever, provided other conditions allow. +Depending on how The Arsse was installed, it will look for configuration in the following places: + +| Installation method | Default database path | +|---------------------|--------------------------------------------------------| +| Arch Linux package | `/etc/webapps/arsse/config.php` | +| Debian package | `/etc/arsse/config.php` | +| Manual installation | `config.php` in the The Arsse's installation directory | + +It is not an error for this file not to exist or to be empty: The Arsse will function with no configuration whatsoever, provided other conditions allow. The configuration file is a PHP script which returns an associative array with keys and values for one or more settings. Any settings which are not specified in the configuration file will be set to their defaults. Invalid values will cause an error on start-up, while unknown keys are ignored. A basic configuration file might look like this: @@ -12,10 +20,10 @@ The configuration file is a PHP script which returns an associative array with k ]; ``` -The `config.defaults.php` file included with copies of The Arsse contains an annotated listing of every configuration setting with its default value. The settings are also documented in more detail below. - # List of all settings +The `config.defaults.php` file included with copies of The Arsse contains an annotated listing of every configuration setting with its default value. The settings are also documented in more detail below. + ## General settings ### lang diff --git a/docs/en/020_Getting_Started/index.md b/docs/en/020_Getting_Started/index.md deleted file mode 100644 index 7feed470..00000000 --- a/docs/en/020_Getting_Started/index.md +++ /dev/null @@ -1,20 +0,0 @@ -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 HTTP Server. - -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](https://php.net/manual/en/book.intl.php), [json](https://php.net/manual/en/book.json.php), [hash](https://php.net/manual/en/book.hash.php), [filter](https://php.net/manual/en/book.filter.php), and [dom](https://php.net/manual/en/book.dom.php) - - [simplexml](https://php.net/manual/en/book.simplexml.php), and [iconv](https://php.net/manual/en/book.iconv.php) - - One of: - - [sqlite3](https://php.net/manual/en/book.sqlite3.php) or [pdo_sqlite](https://php.net/manual/en/ref.pdo-sqlite.php) for SQLite databases - - [pgsql](https://php.net/manual/en/book.pgsql.php) or [pdo_pgsql](https://php.net/manual/en/ref.pdo-pgsql.php) for PostgreSQL 10 or later databases - - [mysqli](https://php.net/manual/en/book.mysqli.php) or [pdo_mysql](https://php.net/manual/en/ref.pdo-mysql.php) for MySQL/Percona 8.0.11 or later databases - - [curl](https://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. diff --git a/docs/en/025_Using_The_Arsse/030_Other_Topics.md b/docs/en/025_Using_The_Arsse/030_Other_Topics.md index 1fe0c4c3..fcebbee9 100644 --- a/docs/en/025_Using_The_Arsse/030_Other_Topics.md +++ b/docs/en/025_Using_The_Arsse/030_Other_Topics.md @@ -1,5 +1,9 @@ [TOC] +# Preface + +This section describes in brief some CLI commands. Please read [the general notes on the command line interface](index) before continuing. + # 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.