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