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