INSTALL.md

   1 # Installation Instructions
   2
   3 ## Simple Install
   4
   5 Execute `sudo make install`. This will do the following:
   6 - create a python virtual environment in `/opt/yt/venv`
   7 - install the software in `/opt/yt/app`
   8 - copy config files to `/etc/yt`
   9
  10 You are then expected to edit `/etc/yt/config.ini` and `/etc/yt/gunicorn-frontend-config.py`.
  11 Finally, run `sudo make finish` to enable the systemd units and start populating the guest feed.
  12
  13
  14 ## Advanced: customizing the installation
  15
  16 You should only read this section if you cannot install using `sudo make install`.
  17
  18 The systemd unit files can be modified to install the software, virtualenv
  19 and/or config files into different locations.
  20 - `WorkingDirectory` should point to the parent directory of `app/`;
  21 - `Environment=PATH` to the virtualenv's `bin/`;
  22 - `Environment=YT_CONFIG` to the `config.ini`.
  23 - The gunicorn config can be set by modifying `ExecStart`.
  24
  25 To allow using classic cronjobs to run the websub/rss jobs, `utils.py` is a
  26 polyglot file that when executed re-launches itself in the virtual environment.
  27 For this to work, the venv must be placed in `venv/` next to the `app/`
  28 directory.
  29
  30 **Do not start the frontend/timers/cronjobs before the database is in place!**
  31
  32 To create the database and tables, simply issue:
  33
  34     sqlite3 subscriptions.sqlite < config/setup.sql
  35
  36 Next, create a user for yourself:
  37
  38         USERN=your_name
  39         PASSWD=$(./config/generate-passwd.py) # will ask
  40         TOKEN=$(head -c16 </dev/urandom|base64|tr /+ _-|tr -d =)
  41         echo "INSERT INTO users(name, password, token) VALUES ('$USERN','$PASSWD','$TOKEN')" |
  42                 sqlite3 subscriptions.sqlite
  43
  44 The homepage will show the guest user's subscription feed. As you cannot log in
  45 as guest, you will have to populate this feed by INSERTing directly into the
  46 datbase. The README's *Advanced Topics* section has information on this. Or you
  47 can use the provided list:
  48
  49         sqlite3 subscriptions.sqlite < config/guest.sql
  50
  51 You can do the same for your own subscriptions, or use the *Subscription
  52 Manager* in the footer of the main page to subscribe to channels manually.
  53
  54 Before starting the frontend, you should run the cronjobs/timers once.
  55 `update.py pull` downloads a back catalog of subscriptions; `update.py websub`
  56 will register for automatic push-updated on new videos. Note that this will
  57 take a long while, as we only do 1 request per minute to Google's RSS endpoints.
  58
  59     systemctl start subscriptions-update@pull.timer
  60     systemctl start subscriptions-update@websub.timer
  61
  62 If you don't want to use a reverse-proxy, [gunicorn can be configured] to
  63 directly serv traffic over TLS by setting a certificate (`certfile`) and
  64 private key (`keyfile`). However, it won't listen on http/tcp to redirect
  65 traffic to https/tcp. For this, a very basic HTTP-to-HTTPS redirect "server" is
  66 available as `subscriptions-port80.service` (requires netcat(1)); it needs the
  67 domain name of your instance in `Environment=DOMAIN=`.
  68
  69 [gunicorn can be configured]: https://docs.gunicorn.org/en/stable/settings.html