INSTALL.md

   1 # Installation Instructions
   2 Note that these instructions are a work in progress and will change during the prototyping phase.
   3
   4 ## 1. Download the Project
   5
   6 Grab and extract a tarball or clone this repository into a convenient location,
   7 e.g. `/opt/yt` (the rest of these instructions will assume this path).
   8
   9         git clone ... /opt/yt
  10         cd /opt/yt
  11
  12 ## 2. Install Virtual Environment
  13
  14 For the most part, it doesn't matter where you set up the virtual environment.
  15 Here, it is created in `/opt/yt/venv`. You eill have to point the systemd unit
  16 files/init scripts and app/common/utils.py to it.
  17
  18         python3 -m venv venv
  19         . venv/bin/activate
  20         pip3 install -r config/requirements.txt
  21         deactivate
  22
  23 ## 3. Configuration
  24
  25 Configuration is read from the `YT_CONFIG` environment variable, falling back
  26 to `/etc/yt/config.ini`. You can keep the `config/` directory untouched to
  27 avoid merge conflicts, and copy the relevant files to `/etc/yt`.
  28
  29 Carefully read and fill out `config/config.ini`. If you want to run the app
  30 directly from gunicorn (as I do), the [Gunicorn configuration] file
  31 (`gunicorn-frontend-config.py`) will need TLS certificate paths. You can ignore
  32 `gunicorn-webhooks-config.py`, unless you want to run it standalone. Otherwise,
  33 configure them to use a high port and reverse-proxy them through your real web
  34 server.
  35
  36 If you want to use the included systemd unit files, point `WorkingDirectory=`
  37 to the location of the repository, `Environment=PATH=` to the location of the
  38 virtualenv's `bin/` directory and `Environment=YT_CONFIG=` to your `config.ini`
  39 (if you aren't using `/etc/yt/config.ini`), as well as the gunicorn config
  40 path. Then copy them to `/etc/systemd/system/`.
  41
  42 **Do not start the frontend before the database and cronjobs are in place!**
  43
  44         cp -r config /etc/yt
  45         cp config/subscriptions-frontend.service /etc/systemd/system
  46
  47         vi /etc/yt/config.ini
  48         vi /etc/yt/gunicorn-frontend-config.py
  49         vi /etc/systemd/system/subscriptions-frontend.service
  50
  51         systemctl daemon-reload
  52         systemctl enable subscriptions-frontend.service
  53
  54 [Gunicorn configuration]: https://docs.gunicorn.org/en/stable/settings.html
  55
  56 ## 4. Create and Prepopulate SQLite Database
  57
  58 To create the database and tables, simply issue:
  59
  60         sqlite3 subscriptions.sqlite < config/setup.sql
  61
  62 Next, create a user for yourself:
  63
  64         USERN=your_name
  65         PASSWD=$(./config/generate-passwd.py) # will ask
  66         TOKEN=$(head -c16 </dev/urandom|base64|tr /+ _-|tr -d =)
  67         echo "INSERT INTO users(name, password, token) VALUES ('$USERN','$PASSWD','$TOKEN')" |
  68                 sqlite3 subscriptions.sqlite
  69
  70 The homepage will show the guest user's subscription feed. As you cannot log in
  71 as guest, you will have to populate this feed by INSERTing directly into the
  72 datbase. The README's *Advanced Topics* section has information on this. Or you
  73 can use the provided list:
  74
  75         sqlite3 subscriptions.sqlite < config/guest.sql
  76
  77 You can do the same for your own subscriptions, or use the *Subscription
  78 Manager* in the footer of the main page to subscribe to channels manually.
  79
  80 ## 5. Set up Cron Jobs
  81
  82 Cronjobs live in app/common/utils.py, which is both a python script and an
  83 executable shell script. When executed with `sh`, it will load the virtual
  84 environment and launch itself with it.
  85
  86 Before starting the frontend, run them once. `cipher` is required to play music
  87 videos; `pull` downloads a back catalog of subscriptions; `websub` will
  88 register for automatic push-updated on new videos. (Note: export `YT_CONFIG` if
  89 you don't use `/etc/yt/config`)
  90
  91         ./app/common/utils.py pull
  92         ./app/common/utils.py websub
  93         ./app/common/utils.py cipher
  94
  95 If all goes well, install them with `crontab -e`. Running `pull` and `cipher`
  96 once per day is plenty; `websub` should run at least twice daily (it won't do
  97 any additional work if ran multiple times, unlike `pull`).
  98
  99         YT_DIR=/opt/yt
 100         # YT_CONFIG=/opt/yt/config/config.ini # optional
 101         19 21 * * * $YT_DIR/app/common/utils.py pull
 102         03 */4 * * * $YT_DIR/app/common/utils.py websub
 103         52 02 * * * $YT_DIR/app/common/utils.py cipher
 104
 105 ## 6. Done
 106
 107 All set -- you can start the frontend now and relax.
 108
 109         systemctl start subscriptions-frontend.service