diff --git a/README.md b/README.md index 8f64314..d6a8cf8 100644 --- a/README.md +++ b/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. diff --git a/screenshot.png b/screenshot.png new file mode 100644 index 0000000..91bd547 Binary files /dev/null and b/screenshot.png differ