Browse Source

Re-organize manual

rpm
J. King 3 years ago
parent
commit
3f3f449da1
  1. 24
      docs/en/020_Getting_Started/020_Download_and_Installation/010_On_Arch_Linux.md
  2. 22
      docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md
  3. 124
      docs/en/020_Getting_Started/030_Web_Server_Configuration.md

24
docs/en/020_Getting_Started/020_Download_and_Installation/010_On_Arch_Linux.md

@ -1,10 +1,10 @@
_[TOC]
[TOC]
# Downloading The Arsse
The Arsse is available from the [Arch User Repository](https://aur.archlinux.org/) as packages `arsse` and `arsse-git`. The latter should normally only be used to test bug fixes.
Since version 0.9.2 The Arsse is available from the [Arch User Repository](https://aur.archlinux.org/) as packages `arsse` and `arsse-git`. The latter should normally only be used to test bug fixes.
Generic release tarballs may also be downloaded [from our Web site](https://thearsse.com). The `PKGBUILD` file (found under `arsse/dist/arch/`) can then be extracted alongside the tarball and used to build the `arsse` package.
Generic release tarballs may also be downloaded [from our Web site](https://thearsse.com), and the `PKGBUILD` file (found under `arsse/dist/arch/`) can then be extracted alongside the tarball and used to build the `arsse` package. Installing directly from the generic release tarball without producing an Arch package is not recommended as the package-building process performs various adjustments to handle Arch peculiarities.
# Installation
@ -13,19 +13,25 @@ For illustrative purposes, this document assumes the `yay` [AUR helper](https://
```sh
# Install the package
sudo yay -S arsse
# Enable the necessary PHP extensions; curl is optional but recommended; pdo_sqlite may be used instead of sqlite, but this is not recommended
# 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
# Enable the necessary systemd units
# Enable and start the necessary systemd units
sudo systemctl enable php-fpm arsse
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 extensions rather than editing `php.ini` as done above.
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.
# Web server configuration
Sample configuration for both Nginx and Apache HTTPd 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.
# 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.
If using a database other than SQLite, you will likely want to [set it up](/en/Getting_Started/Database_Setup) before doing anything else.
In order for the various synchronization protocols to work, a Web server [must be configured](en/Getting_Started/Web_Server_Configuration), and in order for The Arsse to serve users, those users [must be created](/en/Using_The_Arsse/Managing_Users).
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.
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.

22
docs/en/020_Getting_Started/020_Download_and_Installation.md → docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md

@ -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](Requirements) must first be satisfied. The process of installing the required PHP extensions differs from one system to the next, but on Debian the following series of commands should do:
In order for The Arsse to function correctly, its requirements must first be satisfied. The following series of commands should do so:
```sh
# Install PHP; this assumes the FastCGI process manager will be used
@ -30,12 +30,26 @@ sudo chown -R www-data:www-data "/usr/share/arsse"
sudo chmod o+rwX "/usr/share/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.
In order to use Apache HTTPd the FastCGI proxy module must be enabled and the server restarted:
```sh
sudo a2enmod proxy proxy_fcgi
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](Database_Setup) before doing anything else.
If using a database other than SQLite, you will likely want to [set it up](/en/Getting_Started/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).
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.
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.

124
docs/en/020_Getting_Started/030_Web_Server_Configuration.md

@ -1,124 +0,0 @@
[TOC]
# Preface
As a PHP application, The Arsse requires the aid of a Web server in order to communicate with clients. How to install and configure a Web server in general is outside the scope of this document, but this section provides examples and advice for Web server configuration specific to The Arsse. Any server capable of interfacing with PHP should work, though we have only tested Nginx and Apache 2.4.
Samples included here only cover the bare minimum for configuring a virtual host. In particular, configuration for HTTPS (which is highly recommended) is omitted for the sake of clarity
# Configuration for Nginx
```nginx
server {
server_name example.com;
listen 80; # adding HTTPS configuration is highly recommended
root /usr/share/arsse/www; # adjust according to your installation path
location / {
try_files $uri $uri/ =404;
}
location @arsse {
fastcgi_pass unix:/var/run/php/php7.2-fpm.sock; # adjust according to your system configuration
fastcgi_pass_header Authorization; # required if the Arsse is to perform its own HTTP authentication
fastcgi_pass_request_body on;
fastcgi_pass_request_headers on;
fastcgi_intercept_errors off;
fastcgi_buffering off;
fastcgi_param SCRIPT_FILENAME /usr/share/arsse/arsse.php; # adjust according to your installation path
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param REQUEST_URI $uri;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param HTTPS $https if_not_empty;
fastcgi_param REMOTE_USER $remote_user;
}
# Nextcloud News protocol
location /index.php/apps/news/api {
try_files $uri @arsse;
location ~ ^/index\.php/apps/news/api/?$ {
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
}
# Tiny Tiny RSS protocol
location /tt-rss/api {
try_files $uri @arsse;
}
# Tiny Tiny RSS feed icons
location /tt-rss/feed-icons/ {
try_files $uri @arsse;
}
# Tiny Tiny RSS special-feed icons; these are static files
location /tt-rss/images/ {
# this path should not be behind HTTP authentication
try_files $uri =404;
}
# Fever protocol
location /fever/ {
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
# Miniflux protocol
location /v1/ {
try_files $uri @arsse;
}
# Miniflux version number
location /version {
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
# Miniflux "health check"
location /healthcheck {
# this path should not be behind HTTP authentication
try_files $uri @arsse;
}
}
```
# Configuration for Apache2
There are many ways for Apache to interface with PHP, but the recommended way today is to use `mod_proxy` and `mod_proxy_fcgi` to communicate with PHP-FPM. If necessary you can enable these modules on Debian systems using the following commands:
```sh
sudo a2enmod proxy proxy_fcgi
sudo systemctl restart apache2
```
Afterward the follow virtual host configuration should work, after modifying path as appropriate:
```apache
# N.B. the unix:/var/run/php/php7.2-fpm.sock path used repeatedly below will
# vary from system to system and will be probably need to be changed
<VirtualHost *:80>
ServerName localhost
# adjust according to your installation path
DocumentRoot /usr/share/arsse/www
# adjust according to your installation path
ProxyFCGISetEnvIf "true" SCRIPT_FILENAME "/usr/share/arsse/arsse.php"
ProxyPreserveHost On
# Nextcloud News v1.2, Tiny Tiny RSS API, TT-RSS newsfeed icons, Miniflux API
<LocationMatch "(/index\.php/apps/news/api/?.+|/tt-rss/(api|feed-icons)|/v1/)">
ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse"
</LocationMatch>
# Nextcloud News API detection, Fever API, Miniflux miscellanies
<LocationMatch "(/index\.php/apps/news/api/?$|/fever|/version$|/healthcheck$)">
# these locations should not be behind HTTP authentication
ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse"
</LocationMatch>
</VirtualHost>
```
Loading…
Cancel
Save