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