Daniel J. Summers
0c87392910
- Change to SQLite document store - Complete documentation on usage of Feed Reader Central - Update INSTALLING.md for new installation procedures Reviewed-on: #23
70 lines
5.0 KiB
Markdown
70 lines
5.0 KiB
Markdown
# Installation
|
|
|
|
## Obtaining the Files
|
|
|
|
Releases are named `frc-[version]` and are provided in both `.zip` and `.tar.bz2` formats on [the release page](https://git.bitbadger.solutions/bit-badger/feed-reader-central/releases) (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](https://httpd.apache.org/docs/), [nginx](https://nginx.org/en/), and [Caddy](https://caddyserver.com/docs/).
|
|
|
|
### 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](https://frankenphp.dev) 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](https://frankenphp.dev/docs/#standalone-binary) 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](https://www.php.net/manual/en/datetime.format.php) 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.
|