Update README

README.md

@@ -3,3 +3,179 @@
 YouTube on Your Terms
 
 Web App to allow for YouTube subscription management without a Google account.
+
+![Screenshot](./screnshot.png)]
+
+## Discontinued
+
+Note that this is titled "legacy" for a reason. It is generally very old, and
+very ugly. I wrote it when I barely know any PHP or any Perl. It served me well
+for several years, but I'm not proud of it and it is not easy to maintain due to
+it having no real documentation and no real abstraction (the WebUI is a single
+PHP file).
+
+I'm slowly working on implementation a new version written entirely in pure,
+modern Perl. That repository is currently private, but will be made public when
+it reaches approximate parity with this one and I will update this document to
+recommend it.
+
+## Synopsis
+
+This is a web application which is capable of managaging YouTube subscriptions
+without needing a Google account. On top of that, it provides a few other nice
+features:
+
+* Several 'player' options: Links directly to the website, link to the Embedded
+player, link to a 'no-cookie' version of the embedded player, link to a proxied
+version of the embedded player (DuckDuckGo), and copying of the web URL to your
+clipboard.
+* Custom theme support.
+* Ability to sort channels into categories.
+* Ability to search within all subscriptions.
+* Access controls based on connecting IP address.
+
+## Installation
+
+This provides a PHP a web application, but not it's own server. This means you
+need to provide a PHP web server such as [Nginx](https://nginx.org) with a
+[PHP-FPM](https://php-fpm.org) module, or [Apache2](https://httpd.apache.org).
+
+The first steps, regardless of your server application should be the same.
+Clone this repository:
+
+```
+git clone https://git.john.me.tz/jpm/ytyt-legacy.git
+```
+
+Change the ownership of that directory to belong to your web server user. The
+defaults for Debian are included throughout:
+
+```
+chown -R www-data:www-data ytyt-legacy
+```
+
+Now, you can configure your web server to point at the `www/` subdirectory and
+to open `index.php` by default.
+
+### Nginx
+
+These instructions assume that you already have a working version of FPM.
+
+To run this application at a sub-directory of an existing domain, add something
+similar to the following to that `server` block:
+
+```
+    location ^~ /youtube {
+        alias /var/lib/ytyt-legacy/www;
+        index index.php;
+        location ~ \.php$ {
+            include snippets/fastcgi-php.conf;
+            fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
+            fastcgi_param SCRIPT_FILENAME $request_filename/index.php;
+        }
+        access_log /var/log/nginx/youtube_access.log;
+        error_log /var/log/nginx/youtube_error.log;
+        include fastcgi_params;
+    }
+```
+
+Change the following:
+* `/ytyt-legacy` - the path you would like the application to be
+* `/var/lib/ytyt-legacy` - the location where you cloned the
+* `unix:/var/run/php/php7.4-fpm.sock` - the location of the FPM socket (if not
+already configured elsewhere), noting that your version number might differ.
+* `/var/log/nginx/ytyt_access.log` and `/var/log/nginx/ytyt_error.log` - the
+appropriate location for log files.
+
+If you would like to have the application as it's own domain or subdomain, you
+would make a new `server` block with similar information:
+
+```
+server {
+    listen 80 http2;
+    server_name ytyt.example.com;
+    root /var/lib/ytyt-legacy/www;
+    index index.php;
+    location ~ \.php$ {
+        include snippets/fastcgi-php.conf;
+        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
+        fastcgi_param SCRIPT_FILENAME $request_filename/index.php;
+    }
+    access_log /var/log/nginx/youtube_access.log;
+    error_log /var/log/nginx/youtube_error.log;
+    include fastcgi_params;
+}
+```
+
+In addition to the above, you'd also need to change:
+
+* `listen 80` - the desired port(s). You will need to add `ssl_certificate`,
+`ssl_certificate_key`, `ssl_protocols` and `ssl_ciphers` if you would like to
+have HTTPS support.
+* `ytyt.example.com` - your (sub)domain.
+
+You may wish to lock the application behind authentication using `auth_basic` or
+some other mechanism.
+
+Restart nginx once changes have been made.
+
+### Apache2
+
+I have previously tested this in the past, but don't currently have a reference
+configuration. Please see the Apache2 documentation.
+
+## Getting Started
+
+Once you first navigate to the web interface, you will first be invited to
+initialize a database. After doing that, you can start to add subscriptions by
+opening the `+` menu, pasting the channel's URL, and submitting. The feed will
+be fetched immediately, but it will take up to a couple of minutes to finish,
+so you will not see results immediately.
+
+You may also wish to open the gear (settings) menu and immediately update the
+IP access controls to prevent others from being able to read (view) or at least
+write to (modify) your subscriptions and settings.
+
+Once new subscription is added, you can use the `#` icon next to the channel
+avatar to add it to various categories for filtering purposes, or use `/*/` to
+restrict which videos are displayed for that channel based on the title.
+
+If you would like to view only one channel at a time, you can either click the
+channel avatar to be taken to their feed on the YouTube website, or click `✓`
+next to their avatar to have only their videos displayed within the app.
+
+You can us the `X` next to the avatar to remove the subscription.
+
+If you have seen a video and would like to dismiss it from your feed, you can
+use the `X` for that item. This marks it as "seen" and it will no longer appear
+in the results. You can temporarily display these videos again by clicking the
+garbage can icon, then "Show Seen Videos". With that enabled, you have the
+option to mark it as "unseen" again.
+
+Use the magnifying glass icon to search for videos across all channels by title.
+
+Use the rotating arrows icon to force all channels to refresh immediately.
+Again, this will take up to a minute or two, if you have many subscriptions, to
+complete, so you will need to refresh the page.
+
+## Bugs/Shortcomings
+
+As mentioned, the application is poorly written and difficult to maintain.
+
+The biggest issue is that all actions and options are handled using URL
+arguments. There is currently no mechanism to append any currently enabled
+arguments to the end of subsequent requests. This means that settings are lost
+each time the page refreshes. ie. If you are viewing a category, then mark a
+video as played, you will be returned to the full list again and will need to
+re-select the category.
+
+The next biggest issue is that the is no support for muliple accesses to the
+SQLite3 database at the same time, so if a refresh is currently running, it is
+likely that the page will fail to load.
+
+Also, all settings are generally global, regardless of the client. This is
+because no cookies are used. Namely, if you change the theme, it changes for
+everyone. The only exception is that the user agent is checked to provide a
+different layout for mobile users.
+
+There is no form of notification system for new videos.