docs(nginx, phpfpm): improve install and config instructions (#3866)

README.md

@@ -2,12 +2,15 @@
 
 ![RSS-Bridge](static/logo_600px.png)
 
-RSS-Bridge is a web application.
+RSS-Bridge is a PHP web application.
 
 It generates web feeds for websites that don't have one.
 
 Officially hosted instance: https://rss-bridge.org/bridge01/
 
+IRC channel #rssbridge at https://libera.chat/
+
+
 [![LICENSE](https://img.shields.io/badge/license-UNLICENSE-blue.svg)](UNLICENSE)
 [![GitHub release](https://img.shields.io/github/release/rss-bridge/rss-bridge.svg?logo=github)](https://github.com/rss-bridge/rss-bridge/releases/latest)
 [![irc.libera.chat](https://img.shields.io/badge/irc.libera.chat-%23rssbridge-blue.svg)](https://web.libera.chat/#rssbridge)
@@ -48,53 +51,146 @@ Check out RSS-Bridge right now on https://rss-bridge.org/bridge01/
 Alternatively find another
 [public instance](https://rss-bridge.github.io/rss-bridge/General/Public_Hosts.html).
 
-## Tutorial
-
-### Install with composer or git
-
 Requires minimum PHP 7.4.
 
+## Tutorial
+
+### How to install on traditional shared web hosting
+
+RSS-Bridge can basically be unzipped in a web folder. Should be working instantly.
+
+Latest zip as of Sep 2023: https://github.com/RSS-Bridge/rss-bridge/archive/refs/tags/2023-09-24.zip
+
+### How to install on Debian 12 (nginx + php-fpm)
+
+These instructions have been tested on a fresh Debian 12 VM from Digital Ocean (1vcpu-512mb-10gb, 5 USD/month).
+
 ```shell
-apt install nginx php-fpm php-mbstring php-simplexml php-curl
+timedatectl set-timezone Europe/Oslo
+
+apt install git nginx php8.2-fpm php-mbstring php-simplexml php-curl
+
+# Create a new user account
+useradd --shell /bin/bash --create-home rss-bridge
+
+cd /var/www
+
+# Create folder and change ownership
+mkdir rss-bridge && chown rss-bridge:rss-bridge rss-bridge/
+
+# Become user
+su rss-bridge
+
+# Fetch latest master
+git clone https://github.com/RSS-Bridge/rss-bridge.git rss-bridge/
+cd rss-bridge
+
+# Copy over the default config
+cp -v config.default.ini.php config.ini.php
+
+# Give full permissions only to owner (rss-bridge)
+chmod 700 -R ./
+
+# Give read and execute to others (nginx and php-fpm)
+chmod o+rx ./ ./static
+
+# Give read to others (nginx)
+chmod o+r -R ./static
 ```
 
+Nginx config:
+
+```nginx
+# /etc/nginx/sites-enabled/rss-bridge.conf
+
+server {
+    listen 80;
+    server_name example.com;
+    access_log /var/log/nginx/rss-bridge.access.log;
+    error_log /var/log/nginx/rss-bridge.error.log;
+
+    # Intentionally not setting a root folder here
+        
+    # autoindex is off by default but feels good to explicitly turn off
+    autoindex off;
+
+    # Static content only served here 
+    location /static/ {
+        alias /var/www/rss-bridge/static/;
+    }
+
+    # Pass off to php-fpm only when location is exactly /
+    location = / {
+        root /var/www/rss-bridge/;
+        include snippets/fastcgi-php.conf;
+        fastcgi_pass unix:/run/php/rss-bridge.sock;
+    }
+
+    # Reduce spam
+    location = /favicon.ico {
+        access_log off;
+        log_not_found off;
+    }
+
+    # Reduce spam
+    location = /robots.txt {
+        access_log off;
+        log_not_found off;
+    }
+}
+```
+
+PHP FPM pool config:
+```ini
+; /etc/php/8.2/fpm/pool.d/rss-bridge.conf
+
+[rss-bridge]
+
+user = rss-bridge
+group = rss-bridge
+
+listen = /run/php/rss-bridge.sock
+
+listen.owner = www-data
+listen.group = www-data
+
+pm = static
+pm.max_children = 10
+pm.max_requests = 500
+```
+
+PHP ini config:
+```ini
+; /etc/php/8.2/fpm/conf.d/30-rss-bridge.ini
+
+max_execution_time = 20
+memory_limit = 64M
+```
+
+Restart fpm and nginx:
+
+```shell
+# Lint and restart php-fpm
+php-fpm8.2 -t
+systemctl restart php8.2-fpm
+
+# Lint and restart nginx
+nginx -t
+systemctl restart nginx
+```
+
+### How to install from Composer
+
+Install the latest release.
+
 ```shell
 cd /var/www
 composer create-project -v --no-dev rss-bridge/rss-bridge
 ```
 
-```shell
-cd /var/www
-git clone https://github.com/RSS-Bridge/rss-bridge.git
-```
+### How to install with Caddy
 
-Config:
-
-```shell
-# Give the http user write permission to the cache folder
-chown www-data:www-data /var/www/rss-bridge/cache
-
-# Optionally copy over the default config file
-cp config.default.ini.php config.ini.php
-```
-
-Example config for nginx:
-
-```nginx
-# /etc/nginx/sites-enabled/rssbridge
-server {
-    listen 80;
-    server_name example.com;
-    root /var/www/rss-bridge;
-    index index.php;
-
-    location ~ \.php$ {
-        include snippets/fastcgi-php.conf;
-        fastcgi_read_timeout 60s;
-        fastcgi_pass unix:/run/php/php-fpm.sock;
-    }
-}
-```
+TODO. See https://github.com/RSS-Bridge/rss-bridge/issues/3785
 
 ### Install from Docker Hub:
 
@@ -163,6 +259,22 @@ Learn more in
 
 ## How-to
 
+### How to fix "PHP Fatal error:  Uncaught Exception: The FileCache path is not writable"
+
+```shell
+# Give rssbridge ownership
+chown rssbridge:rssbridge -R /var/www/rss-bridge/cache
+
+# Or, give www-data ownership
+chown www-data:www-data -R /var/www/rss-bridge/cache
+
+# Or, give everyone write permission
+chmod 777 -R /var/www/rss-bridge/cache
+
+# Or last ditch effort (CAREFUL)
+rm -rf /var/www/rss-bridge/cache/ && mkdir /var/www/rss-bridge/cache/
+```
+
 ### How to create a new bridge from scratch
 
 Create the new bridge in e.g. `bridges/BearBlogBridge.php`:

caches/FileCache.php

@@ -54,6 +54,7 @@ class FileCache implements CacheInterface
         ];
         $cacheFile = $this->createCacheFile($key);
         $bytes = file_put_contents($cacheFile, serialize($item), LOCK_EX);
+        // todo: Consider tightening the permissions of the created file. It usually allow others to read, depending on umask
         if ($bytes === false) {
             // Consider just logging the error here
             throw new \Exception(sprintf('Failed to write to: %s', $cacheFile));

index.php

@@ -8,7 +8,8 @@ require_once __DIR__ . '/lib/bootstrap.php';
 
 $errors = Configuration::checkInstallation();
 if ($errors) {
-    die('<pre>' . implode("\n", $errors) . '</pre>');
+    print '<pre>' . implode("\n", $errors) . '</pre>';
+    exit(1);
 }
 
 $customConfig = [];