From 3f3f449da17a6220a27909789b677a0e1aa2d13b Mon Sep 17 00:00:00 2001 From: "J. King" Date: Thu, 20 May 2021 10:20:32 -0400 Subject: [PATCH] Re-organize manual --- .../010_On_Arch_Linux.md | 24 ++-- .../020_On_Debian_and_Ubuntu.md} | 22 +++- .../030_Web_Server_Configuration.md | 124 ------------------ 3 files changed, 33 insertions(+), 137 deletions(-) rename docs/en/020_Getting_Started/{020_Download_and_Installation.md => 020_Download_and_Installation/020_On_Debian_and_Ubuntu.md} (59%) delete mode 100644 docs/en/020_Getting_Started/030_Web_Server_Configuration.md 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 fa34b6e1..191af00d 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 @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/en/020_Getting_Started/020_Download_and_Installation.md b/docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md similarity index 59% rename from docs/en/020_Getting_Started/020_Download_and_Installation.md rename to docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md index 19f81082..e753d438 100644 --- a/docs/en/020_Getting_Started/020_Download_and_Installation.md +++ b/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. diff --git a/docs/en/020_Getting_Started/030_Web_Server_Configuration.md b/docs/en/020_Getting_Started/030_Web_Server_Configuration.md deleted file mode 100644 index 8f0371e9..00000000 --- a/docs/en/020_Getting_Started/030_Web_Server_Configuration.md +++ /dev/null @@ -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 - - - 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 - - ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse" - - - # Nextcloud News API detection, Fever API, Miniflux miscellanies - - # these locations should not be behind HTTP authentication - ProxyPass "unix:/var/run/php/php7.2-fpm.sock|fcgi://localhost/usr/share/arsse" - - -```