~hristoast/mousikofidi: site/setup.html

<h1>
  Installation &amp; Setup
</h1>

<p>
  The complete MousikóFídi setup guide!
</p>

<div id="toc"></div>

<h2>Prerequisites</h2>

<p>
  Before running your own MousikóFídi instance, certain requirements must be satisfied:
</p>

<ul>
  <li>
    MousikóFídi has only been tested on GNU/Linux; other OSes should work but are not yet officially supported.
  </li>
  <li>
    A modern version of Python 3 should be installed - though anything above or equal to the latest release of Python 3.5 should work fine.  Pip is also needed to install MousikóFídi itself, as well as its dependencies.
    <ul>
      <li>
        A <code>python3-devel</code> package, or the equivalent for your OS, needs to be present to install <a href="https://uwsgi-docs.readthedocs.io/en/latest/">uWSGI</a>.
      </li>
    </ul>
  </li>
  <li>
    A webserver that supports reverse proxying is needed - this guide recommends and describes how to use <a href="https://nginx.org/">Nginx</a> for this purpose.
  </li>
  <li>
    Last but not least, you will need some audio and or video files for MousikóFídi to serve up!
  </li>
</ul>

<h2>Quickstart</h2>

<p>
  If you just want to run MousikóFídi locally to check it out:
</p>

<pre><code># Add .local/bin to PATH and source if needed
echo 'export PATH=$HOME/.local/bin:$PATH' &gt;&gt; ~/.profile
source ~/.profile

# User install
pip3 install --user MousikoFidi

mousikofidi --dev</code></pre>

<p>
  Now, open <code>http://127.0.0.1:5000/</code> in a browser to use MousikóFídi.  You may also want to <a href="#configuring-mousik--f--di">configure some media sources</a>.
</p>

<h2>Server Quickstart</h2>

<p>
  This section is a high-level look at what you need to do to run MousikóFídi on a server.
</p>

<p>
  Open a terminal and follow the commands shown below:
</p>

<pre><code># First, ensure that the "python3-dev" and "python3-pip"
# packages for your OS are installed and usable.
# ... whatever the method is.
sudo apt install python3-dev python3-pip
sudo dnf install python3-devel python3-pip
sudo pacman -S python3
sudo xbps-install -Su python3-devel python3-pip

# Create a new user to run MousikóFídi as
sudo useradd --create-home --home-dir /opt/fidi fidi

# Become that user
sudo su - fidi

# Add .local/bin to PATH
echo 'export PATH=$HOME/.local/bin:$PATH' &gt;&gt; ~/.profile
source ~/.profile

# Install MousikóFídi
pip3 install --user MousikoFidi

# Fix permissions
chmod 0755 ~/.local
chmod 0755 ~/.local/lib
chmod 0755 ~/.local/lib/python3.*
chmod 0755 ~/.local/lib/python3.*/site-packages

# Run MousikóFídi via the dev server, make sure ~/.local/bin is in $PATH
mousikofidi --dev

# Adjust the config file as needed
vi ~/.config/fidi/config.toml</code></pre>

<p>
  At this point, you are ready to go on to setting up <a href="#configuring-uwsgi">uWSGI</a> and <a href="#configuring-nginx">Nginx</a>.
</p>

<p>
  Continue to the next section for a more detailed breakdown of what is shown above.
</p>

<h2>Installation</h2>

<p>
  Although it is not strictly required, this guide covers running MousikóFídi as its own unprivileged user.
</p>

<h3>Creating the fidi user</h3>

<p>
  MousikóFídi should be run as its own unprivileged user, though keep in mind that it will need read access to wherever your collections are.
</p>

<pre><code>sudo useradd --create-home --home-dir /opt/fidi fidi</code></pre>

<p>
  The home directory is specified as <code>/opt/fidi</code> to avoid any potential permissions and security problems.
</p>

<p>
  From here, become the new user and verify it is usable:
</p>

<pre><code>sudo su - fidi
ls -lah</code></pre>

<h3>Ensure <code>$PATH</code></h3>

<p>
  Before installing MousikóFídi we have to make sure that the install location is in the <code>fidi</code> user's <code>$PATH</code>. If you run this:
</p>

<pre><code>sudo su - fidi
echo $PATH</code></pre>

<p>
  And don't see <code>/opt/fidi/.local/bin</code> in there, then do this:
</p>

<pre><code>sudo su - fidi
echo 'export PATH=$HOME/.local/bin:$PATH' &gt;&gt; ~/.profile
source ~/.profile</code></pre>

<p>
  Now you should be able to successfully run <code>mousikofidi --dev</code> after installing (see below).
</p>

<h3>Installing MousikóFídi</h3>

<pre><code>sudo su - fidi
pip3 install --user MousikoFidi</code></pre>

<p>
  Note that the <code>--user</code> flag is used, which installs all packages under <code>fidi</code>'s home directory, eliminating the need for any superuser access.
</p>

<p>
  Doing this puts all executables under <code>/opt/fidi/.local/bin</code>, so that path must be used or added to the <code>$PATH</code> variable as noted above.
</p>

<p>
  Additionally, it will put static files under a local python library path.  Determine where this is like so:
</p>

<pre><code>sudo su - fidi
ls -d ~/.local/lib/python3.*/site-packages/mousikofidi/static</code></pre>

<p>
  MousikóFídi should now be installed but not yet usable; a configuration file needs to be installed next.
</p>

<h3>Fixing Permissions</h3>

<p>
  There's a good chance that installing MousikóFídi with <code>pip</code> will create directories with very restrictive permissions.  Run these commands to allow the web server user to read them:
</p>

<pre><code>sudo su - fidi
chmod 0755 ~/.local
chmod 0755 ~/.local/lib
chmod 0755 ~/.local/lib/python3.*
chmod 0755 ~/.local/lib/python3.*/site-packages</code></pre>

<h3>Configuring MousikóFídi</h3>

<p>
  Run MousikóFídi like this:
</p>

<pre><code>sudo su - fidi
mousikofidi --dev</code></pre>

<p>
  The first time you run MousikóFídi, a config file will be generated at <code>$HOME/.config/fidi/config.toml</code>.  You can view the contents of this file <a href="https://git.sr.ht/~hristoast/mousikofidi/tree/0349b2c34108638fcaad79a445d4ae7df5eaf58c/mousikofidi/mousikofidi.py#L54-108">in the MousikóFídi source code</a>.
</p>

<p>
  Open this file with a text editor to alter any values as desired:
</p>

<pre><code>sudo su - fidi
vi ~/.config/fidi/config.toml</code></pre>

<p>
  See <a href="/config/#library-dirs">the Config Guide</a> as well as <a href="/user_guide/#adding-your-collection">the User's Guide</a> for more information.
</p>

<p>
  If running on your local machine, at this point you may open <code>http://127.0.0.1:5000/</code> in a browser to use MousikóFídi.
</p>

<p>
  Read on for information about how to run MousikóFídi in production mode.
</p>

<h2>Configuring uWSGI</h2>

<p>
  Using <a href="https://uwsgi-docs.readthedocs.io/en/latest/">uWSGI</a> takes a bit more work, but it is much more performant and the recommended way to run MousikóFídi.
</p>

<p>
  MousikóFídi comes with <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/ece94e3b8bb1aa6df0f4a3e6006f5c3b963cb0c3/example/uwsgi.ini">an example <code>uwsgi.ini</code> file</a> that can be used as a base:
</p>

<pre><code>sudo su - fidi
curl -o ~/.config/fidi/uwsgi.ini https://git.sr.ht/~hristoast/mousikofidi/blob/master/mousikofidi/example/uwsgi.ini</code></pre>

<p>
  Now the <code>pidfile</code> and <code>socket</code> values should be changed to use <code>/opt/fidi/tmp</code> instead of <code>/tmp/</code>, see the example below as a reference:
</p>

<pre><code>[uwsgi]
buffer-size=8192
chmod=660
manage-script-name=true
master=true
max-requests=1000
mount=/=mousikofidi:app
pidfile=/opt/fidi/tmp/mousikofidi.pid
procname=MousikoFidi
socket=/opt/fidi/tmp/mousikofidi.sock
vacuum=true</code></pre>

<p>
  This can be done quickly with <code>sed</code>:
</p>

<pre><code>sudo su - fidi
sed -i "s|/tmp/mousikofidi.pid|/opt/fidi/tmp/mousikofidi.pid|;s|/tmp/mousikofidi.sock|/opt/fidi/tmp/mousikofidi.sock|" ~/.config/fidi/uwsgi.ini</code></pre>

<p>
  Create that directory:
</p>

<pre><code>sudo su - fidi
mkdir ~/tmp</code></pre>

<p>
  MousikóFídi can now be ran via <code>uwsgi</code> and the <code>mousikofidi</code> executable:
</p>

<pre><code>sudo su - fidi
mousikofidi --processes $(nproc)</code></pre>

<p>
  Read on for how to access this via the Nginx HTTP server.
</p>

<h3>uWSGI Daemon</h3>

<p>
  One can optionally run <code>uwsgi</code> in a deamon-like mode, which forks to the background and writes to a log file.
</p>

<p>
  To do this, first create a log directory:
</p>

<pre><code>sudo su - fidi
mkdir ~/logs</code></pre>

<p>
  Then, add the following to <code>/opt/fidi/.config/fidi/uwsgi.ini</code>:
</p>

<pre><code>daemonize=/opt/fidi/logs/uwsgi.log</code></pre>

<p>
  Now, when <code>uwsgi</code> is ran as specified above it will fork into the background.  The specified log can be watched to see requests, errors, and etc.
</p>

<h2>Configuring Nginx</h2>

<p>
  This section requires superuser access to install the MousikóFídi Nginx configuration and enable it, as well as to install Nginx itself.
</p>

<h3>The nginx user</h3>

<p>
  The user that <code>nginx</code> is running as on your system will need read and write access to the socket created by running <code>uwsgi</code>:
</p>

<pre><code>sudo usermod -a -G fidi www-data</code></pre>

<p>
  Where <code>www-data</code> above is the user that the <code>nginx</code> server is running as.
</p>

<p>
  Now, make sure that the <code>fidi</code> group can access <code>/opt/fidi/tmp</code>:
</p>

<pre><code>sudo chmod 0750 /opt/fidi

sudo chmod 0750 /opt/fidi/tmp</code></pre>

<p>
  Read on for a description of how to configure Nginx to read the <code>uwsgi</code> socket.
</p>

<h3>The nginx configuration</h3>

<p>
  Included with MousikóFídi is <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/897ab601f793064307f7ce142cf5eb15598f6998/example/fidi-nginx.conf">an example Nginx configuration file</a> that you may use as a base for your own setup.
</p>

<p>
  Copy this file to where nginx configs are kept:
</p>

<pre><code>curl -o fidi-nginx.conf https://git.sr.ht/~hristoast/mousikofidi/blob/master/mousikofidi/example/fidi-nginx.conf
sudo cp -iv fidi-nginx.conf /etc/nginx/sites-available/</code></pre>

<p>
  The example above is for Debian or Ubuntu; this could go into <code>/etc/nginx/conf.d</code> on other OSes.
</p>

<p>
  Some edits need to be made before this config will actually work:
</p>

<ul>
  <li>
    <p>
      The <code>server_name</code> value should be changed to use an actual domain you control and own (<a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L4">here</a> and <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L14">here</a>).
    </p>
  </li>
  <li>
    <p>
      The <code>ssl_certificate</code> and <code>ssl_certificate_key</code> values (<a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L5">here</a> and <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L15">here</a>) need to be changed with paths to actual self-signed certificates.
    </p>
    <ul>
      <li>
        <p>
          Generate a self-signed cert like this (you can just use the command as-is since the cert is only temporary. Sources: <a href="https://stackoverflow.com/a/10176685">one</a>, <a href="https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-in-ubuntu-16-04#step-1-create-the-ssl-certificate">two</a>):
        </p>
        <pre><code>mkdir /etc/ssl/http
  openssl req -new -newkey rsa:4096 -nodes -x509 -utf8 -sha256 -subj "/C=EARTH/ST=SomePlace/L=SomeWhere/O=Internet/CN=mousikofidi.yourdomain.tld" -days 3650 -keyout /etc/ssl/http/yourdomain.tld.key -out /etc/ssl/http/yourdomain.tld.crt</code></pre>
      </li>
    </ul>
  </li>
  <li>
    <p>
      Ensure the configured log directory (<a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L7">here</a> and <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L18">here</a>) exists, or change it to suit your need:
    </p>
    <pre><code>sudo su - fidi
  mkdir ~/logs</code></pre>
  </li>
  <li>
    <p>
      Same for <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L23">the directory that will be used for the Let's Encrypt challenge</a>:
    </p>
    <pre><code>sudo su - fidi
  mkdir ~/ssl</code></pre>
  </li>
  <li>
    <p>
      Create a password file that will be used for basic auth (This requires the <code>apache2-utils</code> package on Debian/Ubuntu):
    </p>
    <pre><code>sudo su - fidi
htpasswd -c /opt/fidi/.fidiauth YourFidiUserName
chmod 0640 /opt/fidi/.fidiauth</code></pre>
  </li>
  <li>
    <p>
      The basic auth configuration uses <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/462de5f217672af49d4fb1aafda04ef97813ba8f/example/fidi-nginx.conf#L31">fake IP addresses</a>.  Update or remove those.
    </p>
  </li>
  <li>
    <p>
      <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/271d7bd9a1b4c5669d967c4a69efe97414331a1e/example/fidi-nginx.conf#L37">This line</a> needs to point to where <code>pip</code> put the static files.  As noted above, this location can be determined with <code>ls</code>:
    </p>
    <pre><code>sudo su - fidi
  ls -d ~/.local/lib/python3.*/site-packages/mousikofidi/static</code></pre>
  </li>
</ul>

<p>
  Test the nginx configuration before reloading:
</p>

<pre><code>sudo nginx -t</code></pre>

<p>
  If that passes, reload the nginx configuration and MousikóFídi will now be available behind the domain you used for <code>server_name</code> -- but your browser will complain about the certificate being bad.
</p>

<p>
  Read on for a description of how to get a free certificate from <a href="https://letsencrypt.org/">Let's Encrypt</a>.
</p>

<h3>Getting a Let's Encrypt cert</h3>

<p>
  This section also requires superuser access, possibly to install <a href="https://certbot.eff.org/"><code>certbot</code></a> and the related Nginx plugin packages but also to install the certs themselves.
</p>

<p>
  Some OSes offer packages for both <code>certbot</code> and the Nginx plugin, such as Debian and Ubuntu.  If no package is available, check out <a href="https://certbot.eff.org/lets-encrypt/pip-nginx">the Certbot pip-nginx help page</a> and <a href="https://certbot.eff.org/instructions">the Certbot general instructions page</a> page for help getting set up.
</p>

<p>
  At this point, all that's needed to get a certificate is to run certbot:
</p>

<pre><code>certbot --dry-run certonly --nginx -w /opt/fidi/ssl --agree-tos -d mousikofidi.mycooldomain.tld</code></pre>

<p>
  Replace <code>mousikofidi.mycooldomain.tld</code> with your actual configured <code>server_name</code>.
</p>

<p>
  Once the command finishes, a path to the new signed certificate and key files will be displayed.  Copy those paths and paste them into the fidi Nginx configuration over the old values for the self-signed ones.
</p>

<p>
  Test and reload Nginx, and then your MousikóFídi instance should be viewable behind HTTPS on your domain.
</p>

<p>
  Great Job!
</p>

<h2>Running MousikóFídi As A System Service</h2>

<p>
  Running MousikóFídi as a system service is one way to get better control over the process, as well as potential bonus features like auto-restarting and starting at boot.
</p>

<h3>runit</h3>

<p>
  The MousikóFídi demo is behind runit, and the project <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/f0b50a1e5fbb29ffe81d1e0be534c264c61b5fe9/example/runit">includes sample files</a> that can be used as a reference.
</p>

<p>
  All commands in this section require superuser access.
</p>

<ol>
  <li>
    Created the needed directories:
  </li>
</ol>

<pre><code>mkdir /etc/sv/fidi/{control,log,supervise}</code></pre>

<ol>
  <li>
    Create the log <code>run</code> script:
  </li>
</ol>

<pre><code>cat &gt; /etc/sv/fidi/log/run &lt;&lt;EOF
#!/bin/sh
exec logger -t mousikofidi
EOF</code></pre>

<ol>
  <li>
    Create the <code>run</code> script for MousikóFídi itself:
  </li>
</ol>

<pre><code>cat &gt; /etc/sv/fidi/run &lt;&lt;EOF
#!/bin/sh
export LANG=en_US.UTF-8
export USER=fidi
export HOME=/opt/\$USER
export PATH=\$HOME/.local/bin:\$PATH

exec chpst -u \$USER:\$USER uwsgi --ini \$HOME/.config/fidi/uwsgi.ini 2&gt;&amp;1
EOF</code></pre>

<ol>
  <li>
    Create the <code>d</code> script for stopping MousikóFídi:
  </li>
</ol>

<pre><code>cat &gt; /etc/sv/fidi/control/d &lt;&lt;EOF
#!/bin/sh
export LANG=en_US.UTF-8
export USER=fidi
export HOME=/opt/\$USER
export PATH=\$HOME/.local/bin:\$PATH

exec chpst -u \$USER:\$USER uwsgi --stop \$HOME/run/mousikofidi.pid 2&gt;&amp;1
EOF</code></pre>

<ol>
  <li>
    Create the <code>r</code> script for reloading/restarting MousikóFídi:
  </li>
</ol>

<pre><code>cat &gt; /etc/sv/fidi/control/d &lt;&lt;EOF
#!/bin/sh
export LANG=en_US.UTF-8
export USER=fidi
export HOME=/opt/\$USER
export PATH=\$HOME/.local/bin:\$PATH

exec chpst -u \$USER:\$USER uwsgi --reload \$HOME/run/mousikofidi.pid 2&gt;&amp;1
EOF</code></pre>

<ol>
  <li>
    Enable the MousikóFídi service:
  </li>
</ol>

<pre><code>ln -sv /etc/sv/fidi /var/service/</code></pre>

<p>
  Within a few moments, the MousikóFídi should be started.  If you are using some <code>syslog</code> provider, you can check the system logs for details about what's going on:
</p>

<pre><code>tail -f /var/log/messages | grep --color mousikofidi</code></pre>

<ol>
  <li>
    Adjust the MousikóFídi service <code>supervise</code> permissions so the <code>fidi</code> user can manage the service without superuser access:
  </li>
</ol>

<pre><code>chmod 755 /etc/sv/fidi/supervise
chown fidi /etc/sv/fidi/supervise/*</code></pre>

<h4>Commands</h4>

<p>
  The following commands should be used:
</p>

<h5>Reload/Restart</h5>

<p>
  To reload, or restart the MousikóFídi process:
</p>

<pre><code>sv reload fidi</code></pre>

<p>
  <strong>NOTE</strong>: The <code>reload</code> command is not currently known to work with fidi and will likely time out.  If you do this and end up in a bad state, stopping and starting the service should make things right.
</p>

<h5>Start</h5>

<p>
  If the MousikóFídi process is not running, it can be started with any of these:
</p>

<pre><code>sv start fidi

sv u fidi

sv up fidi</code></pre>

<h5>Stop</h5>

<p>
  If the MousikóFídi process is running, it can be stopped with any of these:
</p>

<pre><code>sv stop fidi

sv d fidi

sv down fidi</code></pre>

<h3>SysV Init</h3>

<p>
  While it may be possible to create a traditional init script for MousikóFídi, this is not advised and will not be supported by the project.
</p>

<h3>systemd</h3>

<h4>User Service</h4>

<p>
  The MousikóFídi repo <a href="https://git.sr.ht/%7Ehristoast/mousikofidi/tree/703bfaa81128fe058916f3d430e6e184771e4160/example/mousikofidi.service">includes a sample unit files</a> that can be used with systemd to run the application as a service.
</p>

<p>
  Download the example file and run it as a user service:
</p>

<pre><code>test -d ~/.config/systemd/user || mkdir -p ~/.config/systemd/user
curl -o ~/.config/systemd/user/mousikofidi.service https://git.sr.ht/~hristoast/mousikofidi/blob/master/mousikofidi/example/mousikofidi.service
systemctl --user enable --now mousikofidi.service</code></pre>