The complete MousikóFídi setup guide!


Before running your own MousikóFídi instance certain requirements need to be met:

  • MousikóFídi has only been tested on GNU/Linux; other OSes should work but are not yet officially supported.
  • A modern version of Python 3 - 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.
    • A python3-devel package, or the equivalent for your OS, needs to be present to install uWSGI.
  • A webserver that supports reverse proxying is needed - this guide recommends and describes how to use Nginx for this purpose.
  • Last but not least, you will need some audio and or video files for MousikóFídi to serve up!

Open a terminal, follow the commands shown below:

# 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 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

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

# Fix permissions
chmod 0755 ~/.local
chmod 0755 ~/.local/lib
chmod 0755 ~/.local/lib/python3.6
chmod 0755 ~/.local/lib/python3.6/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.yml

# Re-run MousikóFídi with your tweaked configs
mousikofidi --dev

Now, open in a browser to use MousikóFídi.

Read on for more detailed information about everything, including how to run MousikóFídi in production mode.

Creating the fidi user

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.

sudo useradd --create-home --home-dir /opt/fidi fidi

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

From here, become the new user and verify it is usable:

sudo su - fidi
Installing MousikóFídi
sudo su - fidi
pip3 install --user MousikoFidi

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

Doing this puts all executables under /opt/fidi/.local/bin, so that path must be used or added to the $PATH variable.

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

ls -d ~/.local/lib/python*.*/site-packages/mousikofidi/static

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

Fixing Permissions

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

chmod 0755 ~/.local
chmod 0755 ~/.local/lib
chmod 0755 ~/.local/lib/python3.6
chmod 0755 ~/.local/lib/python3.6/site-packages

You may need to change python3.6 if you're running a different version.

Configuring MousikóFídi

Run MousikóFídi like this:

mousikofidi --dev

The first time you run MousikóFídi, a config file will be generated at $HOME/.config/fidi/config.yml. You can view the contents of this file in the MousikóFídi source code.

Open this file with a text editor to alter any values as desired:

vi ~/.config/fidi/config.yml

See the Config wiki page for more information.

Open in a browser to use MousikóFídi. You may need to re-login or re-source your shell profile for the mousikofidi to be found.

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

Configuring uWSGI

Using uWSGI takes a bit more work, but it is much more performant and the recommended way to run MousikóFídi.

MousikóFídi comes with an example uwsgi.ini file that can be used as a base:

sudo su - fidi
curl -o ~/.config/fidi/uwsgi.ini

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


This can be done quickly with sed:

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

Create that directory:

mkdir ~/tmp

MousikóFídi can now be ran via uwsgi and the mousikofidi executable:

mousikofidi --processes $(nproc)

Read on for how to access this via the Nginx HTTP server.

uWSGI Daemon

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

To do this, first create a log directory:

sudo su - fidi
mkdir ~/logs

Then, add the following to /opt/fidi/.config/fidi/uwsgi.ini:


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

Configuring Nginx

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

The nginx user

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

sudo usermod -a -G fidi www-data

Where www-data above is the user that the nginx server is running as.

Now, make sure that the fidi group can access /opt/fidi/tmp:

sudo chmod 0750 /opt/fidi

sudo chmod 0750 /opt/fidi/tmp

Read on for a description of how to configure Nginx to read the uwsgi socket.

The nginx configuration

Included with MousikóFídi is an example Nginx configuration file. Copy this file to where nginx configs are kept:

sudo cp -iv fidi-nginx.conf /etc/nginx/sites-available/

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

Some edits need to be made before this config will actually work:

  • The server_name value should be changed to use an actual domain you control and own (here and here).

  • The ssl_certificate and ssl_certificate_key values (here and here) need to be changed with paths to actual self-signed certificates.

    • Generate a self-signed cert like this (sources: one, two):

        mkdir /etc/ssl/http
        openssl req -x509 -newkey rsa:4096 -keyout /etc/ssl/http/yourdomain.tld.key -out /etc/ssl/http/yourdomain.tld.crt -days 365
  • Ensure the configured log directory (here and here) exists, or change it to suit your need:

      sudo su - fidi
      mkdir ~/logs
  • Same for the directory that will be used for the Let's Encrypt challenge:

      sudo su - fidi
      mkdir ~/ssl
  • Create a password file that will be used for basic auth:

      # This requires the `apache2-utils` package on Debian/Ubuntu
      sudo su - fidi
      htpasswd -c /opt/fidi/.fidiauth YourFidiUserName
      chmod 0640 /opt/fidi/.fidiauth
  • The basic auth configuration uses fake IP addresses. Update or remove those.

  • This line needs to point to where pip put the static files. As noted above, this location can be determined with ls:

      ls -d ~/.local/lib/python*.*/site-packages/mousikofidi/static

Test the nginx configuration before reloading:

sudo nginx -t

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

Read on for a description of how to get a free certificate from Let's Encrypt.

Getting a Let's Encrypt cert

This section also requires superuser access, possibly to install certbot and the related Nginx plugin packages but also to install the certs themselves.

Some OSes offer packages for both certbot and the Nginx plugin, such as Debian and Ubuntu. If no package is available, check out the Certbot pip-nginx help page and the Certbot general instructions page page for help getting set up.

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

/usr/local/bin/certbot-auto certonly --nginx -w /opt/fidi/ssl --agree-tos -d mousikofidi.mycooldomain.tld

Replace mousikofidi.mycooldomain.tld with your actual configured server_name.

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.

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

Great Job!

Running MousikóFídi As A System Service

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.


The MousikóFídi demo is behind runit, and the project includes sample files that can be used as a reference.

All commands in this section require superuser access.

  1. Created the needed directories:
mkdir /etc/sv/fidi/{control,log,supervise}
  1. Create the log run script:
cat > /etc/sv/fidi/log/run <<EOF
exec logger -t mousikofidi
  1. Create the run script for MousikóFídi itself:
cat > /etc/sv/fidi/run <<EOF
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>&1
  1. Create the d script for stopping MousikóFídi:
cat > /etc/sv/fidi/control/d <<EOF
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/ 2>&1
  1. Create the r script for reloading/restarting MousikóFídi:
cat > /etc/sv/fidi/control/d <<EOF
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/ 2>&1
  1. Enable the MousikóFídi service:
ln -sv /etc/sv/fidi /var/service/

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

tail -f /var/log/messages | grep --color mousikofidi
  1. Adjust the MousikóFídi service supervise permissions so the fidi user can manage the service without superuser access:
chmod 755 /etc/sv/fidi/supervise
chown fidi /etc/sv/fidi/supervise/*

The following commands should be used:


To reload, or restart the MousikóFídi process:

sv reload fidi

NOTE: The reload 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.


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

sv start fidi

sv u fidi

sv up fidi

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

sv stop fidi

sv d fidi

sv down fidi
SysV Init

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.


A systemd unit file for MousikóFídi is planned.

About this wiki

commit c7aa8adde209af4256caa44eb0a930f96d40d5ef
Author: Hristos N. Triantafillou <>
Date:   2019-11-25T12:46:48-06:00

Put the "Contributing" section at the top, mention the dev branch

The way things were before, it wasn't very clear that the "dev" branch
is what someone would want to work off of (need to even).

Moving the "Contributing" section to the top, and adding specific
wording about "dev", will help make this more clear.

I've also swapped out the link for a direct link to
the new "make a patch" link on sourcehut, and removed the bit about
the git book (out of scope for the document anyways).
Clone this wiki (read-only) (read/write)