From 43ab5b55817e105413a564b7a5a65d0bfa439727 Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Tue, 11 Jun 2024 21:58:27 -0400 Subject: [PATCH] Add server configs; update INSTALL verbiage --- INSTALLING.md | 47 ++++++++++++------- src/servers/fastcgi.Caddyfile | 9 ++++ .../frankenphp.Caddyfile} | 3 +- src/servers/htaccess | 5 ++ src/servers/nginx.conf | 27 +++++++++++ 5 files changed, 74 insertions(+), 17 deletions(-) create mode 100644 src/servers/fastcgi.Caddyfile rename src/{Caddyfile => servers/frankenphp.Caddyfile} (53%) create mode 100644 src/servers/htaccess create mode 100644 src/servers/nginx.conf diff --git a/INSTALLING.md b/INSTALLING.md index 047f8ea..79a3664 100644 --- a/INSTALLING.md +++ b/INSTALLING.md @@ -1,30 +1,46 @@ # Installation -## All Environments (FrankenPHP) +## Obtaining the Files -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. +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. -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` +## Selecting a Server -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`. +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/). -Once those steps are complete, from the `/src` directory, run `frankenphp run`. +### Apache 2 -_(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.)_ +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.3, and requires the `curl`, `DOM`, and `SQLite3` modules and the `php-cli` feature. _(FrankenPHP contains all these as part of its build.)_ +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 -## 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. @@ -38,7 +54,7 @@ There are three supported security models, designed around different ways the so ### 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`. +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 @@ -51,4 +67,3 @@ Feed Reader Central tries to keep the database tidy by purging items that have b - `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. - \ No newline at end of file diff --git a/src/servers/fastcgi.Caddyfile b/src/servers/fastcgi.Caddyfile new file mode 100644 index 0000000..04dd073 --- /dev/null +++ b/src/servers/fastcgi.Caddyfile @@ -0,0 +1,9 @@ +# Rename this to Caddyfile and place it in the directory where the release is unarchived +http://localhost:8205 { + root * ./public + # May change based on your PHP FPM configuration + php_fastcgi //unix/run/php/php8.3-fpm.sock { + try_files {path} {path}.php + } + file_server +} diff --git a/src/Caddyfile b/src/servers/frankenphp.Caddyfile similarity index 53% rename from src/Caddyfile rename to src/servers/frankenphp.Caddyfile index 96e6cbc..6f7a0b4 100644 --- a/src/Caddyfile +++ b/src/servers/frankenphp.Caddyfile @@ -1,9 +1,10 @@ +# Rename this to Caddyfile and place it in the directory where the release is unarchived { frankenphp order php_server before file_server } http://localhost:8205 { - root ./public + root * ./public try_files {path} {path}.php php_server } diff --git a/src/servers/htaccess b/src/servers/htaccess new file mode 100644 index 0000000..724b2da --- /dev/null +++ b/src/servers/htaccess @@ -0,0 +1,5 @@ +# Name this .htaccess and place it in the directory where the release is unarchived +RewriteEngine on +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +Rewrite "^(.*)" "$1.php" [QSA,L] diff --git a/src/servers/nginx.conf b/src/servers/nginx.conf new file mode 100644 index 0000000..f4566ad --- /dev/null +++ b/src/servers/nginx.conf @@ -0,0 +1,27 @@ +## nginx Configuration for Feed Reader Central using FastCGI Process Manager (FPM) +server { + server_name server.name; + listen 80; + listen [::]:80; + # /path/to/files is the root directory for the site + access_log /path/to/files/log/access.log; + error_log /path/to/files/log/error.log; + # /path/to/files/app is where the release distribution should be unarchived + root /path/to/files/app/public; + index index.php; + + location ~[^/]\.php(/|$) { + fastcgi_split_path_info ^(.+?\.php)(/.*)$; + if (!-f $document_root$fastcgi_script_name) { + return 404; + } + # This may need to change based on the configuration of PHP FPM + fastcgi_pass unix:/run/php/php8.3-fpm.sock; + fastcgi_index index.php; + include /etc/nginx/fastcgi_params; + } + + location / { + try_files $uri $uri/ $uri.php$is_args$args; + } +}