From 02f46cc08cefe9f643c9a945908000498f279508 Mon Sep 17 00:00:00 2001 From: Greg Sarjeant Date: Sat, 16 Aug 2025 15:57:58 +0000 Subject: [PATCH] update-docs (#74) Update docs for 1.0 release Reviewed-on: https://gitea.subcultureofone.org/greg/tkr/pulls/74 Co-authored-by: Greg Sarjeant Co-committed-by: Greg Sarjeant --- README.md | 231 +++++++++++++++++++++++------------------------------- 1 file changed, 100 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index 5f1ca0f..4c8ab09 100644 --- a/README.md +++ b/README.md @@ -2,95 +2,73 @@ ![Prerequisite tests status](https://gitea.subcultureofone.org/greg/tkr/actions/workflows/prerequisites.yaml/badge.svg) ![Unit tests status](https://gitea.subcultureofone.org/greg/tkr/actions/workflows/unit_tests.yaml/badge.svg) -A lightweight, HTML-only status feed for self-hosted personal websites. Written in PHP. Heavily inspired by [status.cafe](https://status.cafe). +A simple, HTML-only status feed for self-hosted personal websites. Written in PHP. Heavily inspired by [status.cafe](https://status.cafe). -## Screenshots +## Requirements -### Mobile - -tkr logged out view - mobile -tkr logged in view - mobile - -### Desktop - -tkr logged in view - desktop - -tkr logged in view - desktop - -## Features - -* HTML and CSS implementation. No Javascript. -* Accessible by default -* RSS `/rss` and Atom `/atom` feeds -* CSS uploads for custom theming -* Custom emoji to personalize moods (unicode only) - -I'm trying to make sure that the HTML is both semantically valid and accessible, but I have a lot to learn about both. If you see something I should fix, please let me know! - -## Prerequisites - -* A web server with PHP support, such as: - * Apache with mod_php - * nginx and php-fpm -* PHP 8.2+ with the PDO and PDO_SQLITE extensions - * The PDO and PDO_SQLITE extensions are usually included by default - * This might work with earlier PHP versions, but I've only tested 8.2 +* A server running Linux +* A web server, such as apache or nginx + * Web server configs are in the `examples` directory +* PHP 8.2+ + * Required extensions: + * [PDO](https://www.php.net/pdo) + * [PDO_SQLITE](https://www.php.net/pdo-sqlite) + * Recommended extensions: + * [mbstring](https://www.php.net/mbstring) + * [fileinfo](https://www.php.net/fileinfo) ## Installation -1. Download the latest tkr archive from [the packages page](https://gitea.subcultureofone.org/greg/tkr/packages) -1. Copy the `.tgz` file to your server and extract it -1. Copy the `tkr` directory to the location you want to serve it from - * on debian-based systems, `/var/www/tkr` is recommended -1. Make the `storage` directory writable by the web server account. - ```sh - chown www-data:www-data /path/to/tkr/storage - chmod 0770 /path/to/tkr/storage - ``` -1. Add the necessary web server configuration. - * Examples for common scenarios can be found in the [examples](./examples) directory. - * Apache VPS, subdomain (e.g. `https://tkr.your-domain.com`): [examples/apache/vps/root](./examples/apache/vps/root) - * Apache VPS, subfolder (e.g. `https://your-domain.com/tkr`): [examples/apache/vps/subfolder](./examples/apache/vps/subfolder) - * Nginx VPS, subdomain (e.g. `https://tkr.your-domain.com`): [examples/nginx/root](./examples/nginx/root) - * Nginx VPS, subfolder (e.g. `https://your-domain.com/tkr`): [examples/nginx/subfolder](./examples/nginx/subfolder) - * Any values that need to be configured for your environment are labeled with `CONFIG`. - * The SSL configurations are basic, but should work. For more robust SSL configurations, see https://ssl-config.mozilla.org +1. Get the latest package from https://gitea.subcultureofone.org/greg/tkr/packages +1. Copy it to your web server +1. Set up the directory permissions: + * `tkr/storage` must be writable by the web server account + * `www-data` on debian-based systems + * `apache` on redhat-based systems + * All other `tkr` directories should be *readable* by the web server account. + * For example, if you're on debian: + ```sh + # Make 'root' the owner of everything under 'tkr' + chown -R root:root tkr + # Make 'www-data' the owner of everything under 'tkr/storage' + chown -R www-data:www-data tkr/storage -## Initial configuration + # Make 'tkr/storage' writable bt 'www-data' + chmod 0770 tkr/storage + ``` +1. Configure your web server for your environment and serving model: + * There are example web server configs for common scenarios in the `examples` directory. + * apache shared hosting (e.g. everything served from `public_html`, .htaccess only) + * apache VPS + * subfolder: e.g. https://example.com/tkr + * subdomain: e.g. https://tke.example.com + * nginx VPS + * subfolder: e.g. https://example.com/tkr + * subdomain: e.g. https://tke.example.com + * Expose only the `public` folder if possible + * The VPS examples are configured this way. + * If this isn't possible (e.g. shared hosting), it's okay. There are `.htaccess` files included to block access to other directories in shared hosting environments. +1. Run the installation: + * Browser-based: + * Navigate to the tkr site (e.g. https://my-domain.org/tkr or https://tkr.my-domain.org) + * You'll be presented with the setup page. + * Complete the required fields. + * Command-line: + * ssh to your web server + * run `php /path/to/tkr/tkr-setup.php` -1. Run `php tkr/prerequisites.php`. This will confirm that: - 1. PHP 8.2+ is installed - 1. All required PHP extensions are installed - 1. PDO - 1. PDO::sqlite - 1. All required directories exist - 1. The `tkr/storage` directory exists and is writable - 1. If `tkr/storage` is writable, then it will create the required subdirectories - 1. `tkr/storage/db` - 1. `tkr/storage/upload` - 1. The script will write a summary to stdout and will save a log at `tkr/storage/prerequisite-check.log` -1. Edit `config/init.php` to set the domain and base path correctly for your configuration. - * subdirectory installation (e.g. https://my-domain.com/tkr) - ``` - 'base_url' => 'https://my-domain.com', - 'base_path' => '/tkr/', - ``` - * subdomain installation (e.g. https://tkr.my-domain.com) - ``` - 'base_url' => 'https://tkr.my-domain.com', - 'base_path' => '/', - ``` -1. Browse to your tkr URL. You'll be presented with the setup screen to complete initial configuration. -![tkr setup page](https://subcultureofone.org/images/tkr/tkr-setup.png) +If any prerequisites are missing (required PHP extensions, directory permissions) + +## Features + +* RSS `/rss` and Atom `/atom` feeds +* HTML and CSS implementation. No Javascript. +* Accessible HTML, with strict accessibility settng to aid tab navigation +* CSS uploads for custom theming +* Custom emoji to personalize moods + +I'm trying to make sure that the HTML is both semantically valid and accessible, but I have a lot to learn about both. If you see something I should fix, please let me know! ### Server configuration notes @@ -108,8 +86,7 @@ There is an `.htaccess` file in the `tkr/` root directory. It's designed for the * `tkr/storage` * `tkr/templates` - -### Docker compose +### Docker compose (local development) The [docker](./docker) directory contains docker-compose.yml files and web server configs for some different server configurations. For simplicity, these do not use SSL. @@ -117,44 +94,62 @@ To run tkr locally on your machine, copy the docker-compose file you're interest ## Accessibility Note -The "Strict Accessibility" setting (enabled by default) addes `tabindex="0"` to all `` tags to force them to get tab focus. This isn't strictly best practice. The `` tag should get tab focus by default. But I've learned that some browsers (at least Safari and Vivaldi) disable this in their default configurations, making accessibility an opt-in feature. +The "Strict Accessibility" setting (enabled by default) adds `tabindex="0"` to all `` tags to force them to get tab focus. This isn't strictly best practice. The `` tag should get tab focus by default. But I've learned that some browsers (at least Safari and Vivaldi) disable this in their default configurations, making accessibility an opt-in feature. If you'd like to revert to the standard behavior, toggle this setting off. But know that people who navigate by keyboard may have to reconfigure their browser settings in order to select hyperlinks. ## Storage -Ticks are stored in files on the filesystem under `/tkr/storage/ticks`. This directory must be writable by the web server user and so SHOULD NOT be served by the web server. If you set your document root to `/tkr/public/`, then you'll be fine. +tkr stores data at `tkr/storage`. This directory must be writable by the web server account and so *should not* be served by the web server. If you made `tkr/public` your document root, then you're fine. If you can't, then the .htaccess file in that directory will block access if you're running apache. -The file structure is `YYYY/MM/DD.txt`. That is, each day's ticks are located in a file whose full path is `/tkr/storage/ticks/YEAR/MONTH/DAY.txt`. This is to prevent any single file from getting too large. +There are 3 subdirectories: -Each entry takes the form `TIMESTAMP|TICK`, where `TIMESTAMP` is the time that the entry was made and `TICK` is the text of the entry. +* `tkr/storage/db`: + * Contains a sqlite database: `tkr.sqlite`. + * The database contains site settings, user profile data, ticks, and custom emoji. +* `tkr/storage/logs`: + * Runtime log files. + * Logs rotate after 1,000 lines. + * The last 5 log files are retained. +* `tkr/storage/uploads`: + * Stores custom CSS for personalized theming -For illustration, here's a sample from the file `/tkr/storage/ticks/2025/05/25` on my test system. - -```sh -# cat /tkr/ticks/2025/05/25.txt -23:27:37|some stuff -23:27:45|some more, stuff -``` - -### SQLite Database - -tkr stores profile information, custom emojis, and uploaded css metadata in a SQLite database located at `tkr/storage/db/tkr.sqlite`. +### SQLite Database Note You don't have to do any database setup. The database is automatically created and initialized on first run. -## FAQ +## Backup and restore -### Why don't I see the right IPs in the logs? +tkr is completely self-contained. To back up tkr, just zip up the `tkr` directory and copy it to your backup location. To restore it, unzip it in the new location. -This can happen for a few reasons. Some common ones are: +Technically, you only need back up and restore the `tkr/storage` directory if you want to minimize the size of the backup, but the app is pretty small (~40 Kb compressed). -**Docker Development:** If running via Docker, you may see `192.168.65.1` (Docker Desktop gateway). This is normal for development. +## Screenshots -**Behind a Proxy/CDN:** If you're behind Cloudflare (with proxy enabled), load balancers, or other proxies, all requests may appear to come from the proxy's IP addresses. +### Mobile -- **For accurate IP logging:** Configure your web server to trust proxy headers. See your proxy provider's documentation for the required nginx/Apache configuration. +tkr logged out view - mobile +tkr logged in view - mobile +### Desktop + +tkr logged out view - desktop + +tkr logged in view - desktop + +### Setup validation failure example + +tkr setup validation failure ## Acknowledgements @@ -162,30 +157,4 @@ It's been a lot of fun to get back to building something. I'm grateful to the pe * [armaina](https://armaina.com) - Armaina's a talented artist (check out the site!) who had the original idea for a self-hosted PHP version of status.cafe. That sounded like a fun project so I thought I'd see if I could manage it. This project doesn't exist without Armaina. Thank you! * [status.cafe](https://status.cafe) - The technological inspiration. Unless you really want to self-host, you should use status.cafe instead! I took a lot of inspiration from its design and then I made the CSS way heavier and probably lost some of the soul along the way. -* [32-bit cafe](https://32bit.cafe) - I started in technology as a hobbyist and idealist. Then I became a professional. The decades since have sucked the joy and the hope out of technology. 32-bit cafe reminded me that they're both still there. - -## Tentative 0.y.z releases to 1.0 - -I'd like to alternate beteen architecture and feature releases between here and 1.0. This is my current thinking, but these may change. - -### 0.7.5 (architecture improvements) -* Add linting and tests -* Add artifact build pipeline - -### 0.8.0 (features and enhancements) -* Support microformats -* Support h-feed and JSON - -### 0.8.5 (architecture improvements) -* Add docker build and deployment - -### 0.9.0 (features and enhancements) -* Allow customization of time zone and time display for ticks - -### 0.9.5 (architecture enhancements) -* Improve exception handling -* Add logging, including log viewer screen - -### 1.0.0 -* Polish README and other docs -* Set up dedicated webpage \ No newline at end of file +* [32-bit cafe](https://32bit.cafe) - I started in technology as a hobbyist and idealist. Then I became a professional. The decades since have sucked the joy and the hope out of technology. 32-bit cafe reminded me that they're both still there. \ No newline at end of file