feed-reader-central/INSTALLING.md

Installation

All Environments (FrankenPHP)

The easiest way to get up and running quickly is by using FrankenPHP, a version of Caddy that runs PHP in its process. There is a Caddyfile in the /src directory which will configure the site to run with FrankenPHP.

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.

(More environments will be detailed as part of a later release; an nginx reverse proxy via FastCGI is another common way to run PHP applications.)

PHP Requirements

This is written to target PHP 8.3, 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

Site Address

The default Caddyfile will run the site at http://localhost:8205. To have the process respond to other devices on your network, you can add the server name to that to line 5 (ex. http://localhost:8205, http://server:8205); you can also change the port on which it listens. (Note that if http is not specified, Caddy will attempt to obtain and install a server certificate. This may be what you want, but that also could be a source of startup errors.)

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 under the /src/data directory, 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 /src/data, not just /src.

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.