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