151 lines
6.0 KiB
Markdown
151 lines
6.0 KiB
Markdown
# tkr
|
|
|
|
A lightweight, HTML-only status feed for self-hosted personal websites. Written in PHP. Heavily inspired by [status.cafe](https://status.cafe).
|
|
|
|
## Screenshots
|
|
|
|
### Mobile
|
|
|
|
<img src="https://subcultureofone.org/images/tkr/tkr-logged-out-mobile.png"
|
|
alt="tkr logged out view - mobile"
|
|
width="40%" height="40%">
|
|
<img src="https://subcultureofone.org/images/tkr/tkr-logged-in-mobile.png"
|
|
alt="tkr logged in view - mobile"
|
|
width="40%" height="40%">
|
|
|
|
### Desktop
|
|
|
|
<img src="https://subcultureofone.org/images/tkr/tkr-logged-out-desktop.png"
|
|
alt="tkr logged in view - desktop"
|
|
width="60%" height="60%">
|
|
|
|
<img src="https://subcultureofone.org/images/tkr/tkr-logged-in-desktop.png"
|
|
alt="tkr logged in view - desktop"
|
|
width="60%" height="60%">
|
|
|
|
|
|
|
|
## Features
|
|
|
|
* HTML and CSS implementation. No Javascript.
|
|
* RSS `/feed/rss` and Atom `/feed/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
|
|
|
|
## Installation
|
|
|
|
1. Download the latest tkr archive from https://subcultureofone.org/files/tkr/tkr.0.6.0.zip
|
|
1. Copy the .zip 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
|
|
|
|
|
|
### From git
|
|
|
|
If you'd prefer to install from git:
|
|
|
|
1. Clone this directory and copy the `/tkr` directory to your web server.
|
|
* Required subdirectories are:
|
|
1. `config`
|
|
1. `public`
|
|
1. `src`
|
|
1. `storage`
|
|
1. `templates`
|
|
* Exclude the other directories
|
|
2. Follow the main installation from step 4.
|
|
|
|
## Initial configuration
|
|
|
|
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.
|
|
|
|
|
|
## Server configuration notes
|
|
|
|
The document root should be `/PATH/TO/tkr/public`. This will ensure that only the files that need to be accessible from the internet are served by your web server.
|
|
|
|
There is an `.htaccess` file in the `tkr/` root directory. It's designed for the following installation scenario:
|
|
|
|
* shared hosting
|
|
* `tkr/` is installed to `tkr/` under your web root. (e.g. `public_html/tkr`).
|
|
* `tkr/public` is the document root
|
|
* The other application directories are blocked both by `tkr/.htaccess` and by `.htaccess` files in the directories themselves. These are:
|
|
* `tkr/config`
|
|
* `tkr/examples` (not technically an application directory, but distributed with the .zip archive)
|
|
* `tkr/src`
|
|
* `tkr/storage`
|
|
* `tkr/templates`
|
|
|
|
|
|
### Docker compose
|
|
|
|
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.
|
|
|
|
To run tkr locally on your machine, copy the docker-compose file you're interested in to `tkr/` and run `docker compose up`.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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`.
|
|
|
|
You don't have to do any database setup. The database is automatically created and initialized on first run.
|
|
|
|
## TODO
|
|
|
|
* Validate HTML semantics on all pages
|
|
* Validate accessibility on all pages
|
|
* Add logging, including log viewer screen
|
|
* Improve exception handling
|
|
* Support microformats
|
|
* Support h-feed and JSON
|
|
* Allow customization of time zone and time display for ticks
|
|
* Probably a bunch of other stuff I'm not thinking of |