From fe16ec7281f29fdb4ff978bf9c011dbd2715ea67 Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Sat, 13 Apr 2024 23:15:48 -0400 Subject: [PATCH] Add installation dox --- INSTALLING.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 8 ++++++-- 2 files changed, 51 insertions(+), 2 deletions(-) create mode 100644 INSTALLING.md diff --git a/INSTALLING.md b/INSTALLING.md new file mode 100644 index 0000000..d8d4dea --- /dev/null +++ b/INSTALLING.md @@ -0,0 +1,45 @@ +# Installation + +## All Environments (FrankenPHP) + +The easiest way to get up and running quickly is by using [FrankenPHP](https://frankenphp.dev), a version of [Caddy](https://caddyserver.com) 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](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`. + +_(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. _(FrankenPHP contains these modules as part of its build.)_ + +# Setup and Configuration + +## Site Address + +The default `Caddyfile` will run the site at `http://localhost:8205`. To change that, change that address on line 5. (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.php`. This file is the place for customizations and configuration of the instance's behavior. + +### Security Model + +There ~~are~~ will be three supported security models, designed around different ways the software may be deployed. +- `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` _(not yet implemented)_ will be the same as the above, but will require 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` _(not yet implemented)_ will require a known e-mail address and password be provided to establish the identity of each user. This will be 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](https://www.php.net/manual/en/datetime.format.php) is supported. \ No newline at end of file diff --git a/README.md b/README.md index 086cab3..1b8caaa 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ -# feed-reader-central +# Feed Reader Central -A centralized, lightweight feed reader with simple self-hosting \ No newline at end of file +Feed Reader Central is a lightweight feed reader with simple self-hosting. The self-hosted instance serves as a place where feeds can be read and referenced from different devices. + +It is written in vanilla PHP, and uses a SQLite database to keep track of items. + +See [INSTALLING.md](/INSTALLING.md) for setup and configuration instructions.