INSTALL.md

   1 # Installation Instructions
   2
   3 ## Simple Install
   4
   5 Execute `sudo make install`. This will do the following:
   6
   7 - create a python virtual environment in `/opt/yt/venv`
   8 - install the software in `/opt/yt/app`
   9 - copy config files to `/etc/yt`
  10
  11 You are then expected to edit `/etc/yt/config.ini` and set `[webhooks]` ->
  12 `public_uri` to the domain (and port) you're running this on. Feel free to
  13 change the `welcome_message` or disable unneeded `modules`.
  14
  15 By default, the web frontend will run unencrypted on port 8080; this can be
  16 changed in `/etc/yt/gunicorn-frontend-config.py`. Alternatively, run it from
  17 behind a reverse-proxy.
  18
  19 Finally, run `sudo make finish` to enable and start the systemd units and start
  20 populating the guest feed.
  21
  22 A user `admin` is created, with the password `admin`. You should change that!
  23 Either use this user for yourself, or create a new user on the admin's account
  24 settings page.
  25
  26 ## Advanced: customizing the installation
  27
  28 The following is more a list of possibilities than one of recommendations. It's
  29 best to just stick to the normal installation with `make install`.
  30
  31 The systemd unit files can be modified to install the software, virtualenv
  32 and/or config files into different locations.
  33
  34 - `WorkingDirectory` should point to the parent directory of `app/`;
  35 - `Environment=PATH` to the virtualenv's `bin/`;
  36 - `Environment=YT_CONFIG` to the `config.ini`.
  37 - The gunicorn config can be set by modifying `ExecStart`.
  38
  39 To allow using classic cronjobs to run the websub/rss jobs, `utils.py` is a
  40 polyglot file that when executed re-launches itself in the virtual environment.
  41 For this to work, the venv must be placed in `venv/` next to the `app/`
  42 directory.
  43
  44 **Do not start the frontend/timers/cronjobs before the database is in place!**
  45
  46 To create the database and tables, simply issue:
  47
  48     sqlite3 subscriptions.sqlite < config/setup.sql
  49
  50 If you do not want to use the admin account automatically created, one can be
  51 created manually. Note that the password is written into the database in plain
  52 text and should be changed from the web UI after logging in.
  53
  54         USERN=your_name
  55         PASSWD='plain$$your_password'  # 'plain$$' prefixed
  56         TOKEN=$(head -c16 </dev/urandom|base64|tr /+ _-|tr -d =)
  57         echo "INSERT INTO users(name, password, token, is_admin) VALUES ('$USERN','$PASSWD','$TOKEN', 1)" |
  58                 sqlite3 subscriptions.sqlite
  59
  60 The homepage will show the guest user's subscription feed. As you cannot log in
  61 as guest, you will have to populate this feed by INSERTing directly into the
  62 datbase. The README's *Advanced Topics* section has information on this. Or you
  63 can use the provided list:
  64
  65         sqlite3 subscriptions.sqlite < config/guest.sql
  66
  67 You can do the same for your own subscriptions, or use the *Subscription
  68 Manager* in the footer of the main page to subscribe to channels manually.
  69
  70 Before starting the frontend, you should run the cronjobs/timers once.
  71 `update.py pull` downloads a back catalog of subscriptions; `update.py websub`
  72 will register for automatic push-updated on new videos. Note that this will
  73 take a long while, as we only do 1 request per minute to Google's RSS endpoints.
  74
  75     systemctl start subscriptions-update@pull.timer
  76     systemctl start subscriptions-update@websub.timer
  77
  78 If you don't want to use a reverse-proxy, [gunicorn can be configured] to
  79 directly serv traffic over TLS by setting a certificate (`certfile`) and
  80 private key (`keyfile`). However, it won't listen on http/tcp to redirect
  81 traffic to https/tcp. For this, a very basic HTTP-to-HTTPS redirect "server" is
  82 available as `subscriptions-port80.service` (requires netcat(1)); it needs the
  83 domain name of your instance in `Environment=DOMAIN=`.
  84
  85 [gunicorn can be configured]: https://docs.gunicorn.org/en/stable/settings.html
  86
  87 It is possible to run the `webhooks` blueprint as a standalone flask app. This
  88 can be useful to still receive new video notifications, even while the frontend
  89 is offline. Copy `subscriptions-frontend.service` and change `ExecStart` like
  90 so:
  91
  92     ExecStart=/usr/bin/env gunicorn --config /etc/yt/gunicorn-webhooks-config.py 'app.webhooks:app()'
  93
  94 In `config.ini`, update `[webhooks] public_uri` and optionally remove
  95 `webhooks` from the `[frontend] modules` list (it will be unused, but shouldn't
  96 hurt). Configure `gunicorn-webhooks-config.py` to listen on a seperate port;
  97 TLS is optional.
  98
  99 All `[frontend] modules` except `youtube` are optional and can be disabled if
 100 desired. Let's look at what each of them does:
 101
 102 - `youtube`: allows watching videos and handles the subscription feed. channel
 103   and playlist pages only shows the last 15 uploads.
 104 - `browse`: implements search, extends the channel/playlist pages to full
 105   functionality.
 106 - `webhooks`: receives notifications from Youtube about new uploads. If
 107   disabled, the subscription feed will be updated from rss feeds once per day.
 108 - `proxy`: livestreams and geolocked videos must be proxied to work. If
 109   disabled, an error is shown when such a video is requested.
 110 - `reddit`: shows videos uploaded to specific subreddits (mainly, /r/videos).
 111   Logged in users can configure their subscribed subreddits.