feed-reader-central/INSTALLING.md

Installation

Obtaining the Files

Releases are named frc-[version] and are provided in both .zip and .tar.bz2 formats on the release page (starting with beta1). Select a folder on the server that will host this instance and unarchive the release there.

Selecting a Server

Configuration samples are provided in the /servers directory for Apache 2, nginx, and Caddy.

Apache 2

Configure a virtual host (if appropriate), then copy /servers/htaccess to .htaccess in the directory where the release archive was expanded. This file enables the extensionless rewrites required for the URLs to work.

nginx

The configuration file /servers/nginx.conf is a full virtual host configuration. Update it with the paths for your installation, then add it to your configuration (on Debian/Ubuntu, copy it to /etc/nginx/sites-available, create a symlink in /etc/nginx/sites-enabed, and reload the nginx config).

Caddy (with FastCGI)

/servers/fastcgi.Caddyfile contains configuration to host the site using Caddy. Ensure the PHP FPM address is correct, then rename it to Caddyfile and place it in the directory where the release archive was expanded. Running caddy run will serve the site with the given parameters.

Caddy (with FrankenPHP)

NOTE: This is currently not recommended. There is a known sequence of links that cause FrankenPHP to no longer respond. Hopefully this will be resolved before the beta moniker is dropped.

FrankenPHP is a version of Caddy that runs PHP in its process. /servers/frankenphp.Caddyfile will configure the site to run with FrankenPHP.

Obtain a version for Linux / Mac users:

• Follow their instructions for downloading a binary for your system
• Rename that binary to frankenphp and make it executable (chmod +x ./frankenphp)
• Move that binary to /usr/local/bin

For Windows users, the steps are the same; however, the binary should be named frankenphp.exe and be placed somewhere within your system's PATH.

Once those steps are complete, from the /src directory, run frankenphp run.

PHP Requirements

This is written to target PHP 8.2, and requires the curl, DOM, and SQLite3 modules and the php-cli feature. (FrankenPHP contains all these as part of its build.)

Setup and Configuration

Feed Reader Central Behavior

Within the /src directory, there is a file named user-config.dist.php. Rename this file to user-config.php; this is where customizations and configuration of the instance's behavior are placed.

Security Model

There are three supported security models, designed around different ways the software may be deployed. SECURITY_MODEL in user-config.php must be set to one of these values.

• Securty::SINGLE_USER assumes that all connections to the instance are the same person. There is no password required, and no username or e-mail address will be displayed for that user. This is a good setup for a single user on a home intranet. DO NOT PUT AN INSTANCE WITH THIS CONFIGURATION ON THE PUBLIC INTERNET! If you do, you deserve what you get.
• Security::SINGLE_USER_WITH_PASSWORD is the same as the above but requires a password. This setup is ideal for intranets where the user does not want any other users ending up marking their feeds as read just by browsing them.
• Security::MULTI_USER requires a known e-mail address and password be provided to establish the identity of each user. This is the most appropriate setup for an Internet-facing instance, even if there is only one user.

Database Name

Data is stored in the /data subdirectory of the release extraction location, and the default database name is frc.db. If users want to change that path or file name, the path provided should be relative to /data.

Date/Time Format

The default format for dates and times look like "May 28, 2023 at 3:15pm". Changing the string there will alter the display on the main page and when reading an item. Any supported PHP date or time token is supported.

Item Purging

Feed Reader Central tries to keep the database tidy by purging items that have been read and are no longer required. There are four variants:

• Feed::PURGE_NONE does no purging (items have a "Delete" button, so they may be deleted manually)
• Feed::PURGE_READ purges non-bookmarked read items for a feed whenever it is refreshed. This is the most aggressive purging strategy, but it is also the only one that will not purge unread items.
• Feed::PURGE_BY_DAYS purges non-bookmarked items that are older than PURGE_NUMBER days old. This is the default value, and PURGE_NUMBER's default value is 30; items will be kept for 30 days, read or unread.
• Feed::PURGE_BY_COUNT purges items to preserve at most PURGE_NUMBER non-bookmarked items for each feed.