The complete MousikóFídi setup guide!
Before running your own MousikóFídi instance, certain requirements must be satisfied:
python3-develpackage, or the equivalent for your OS, needs to be present to install uWSGI.
If you just want to run MousikóFídi locally to check it out:
# Add .local/bin to PATH and source if needed echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile source ~/.profile # User install pip3 install --user git+https://git.sr.ht/~hristoast/mousikofidi@master mousikofidi --dev
http://127.0.0.1:5000/ in a browser to use MousikóFídi. You may also want to configure some media sources.
This section is a high-level look at what you need to do to run MousikóFídi on a server.
Open a terminal and 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 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' >> ~/.profile source ~/.profile # Install MousikóFídi pip3 install --user git+https://git.sr.ht/~hristoast/mousikofidi@master # 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
At this point, you are ready to go on to setting up uWSGI and Nginx.
Continue to the next section for a more detailed breakdown of what is shown above.
Although it is not strictly required, this guide covers running MousikóFídi as its own unprivileged 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 ls -lah
Before installing MousikóFídi we have to make sure that the install location is in the
$PATH. If you run this:
sudo su - fidi echo $PATH
And don't see
/opt/fidi/.local/bin in there, then do this:
sudo su - fidi echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile source ~/.profile
Now you should be able to successfully run
mousikofidi --dev after installing (see below).
sudo su - fidi pip3 install --user git+https://git.sr.ht/~hristoast/mousikofidi@master
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 as noted above.
Additionally, it will put static files under a local python library path. Determine where this is like so:
sudo su - fidi ls -d ~/.local/lib/python3.*/site-packages/mousikofidi/static
MousikóFídi should now be installed but not yet usable; a configuration file needs to be installed next.
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:
sudo su - fidi chmod 0755 ~/.local chmod 0755 ~/.local/lib chmod 0755 ~/.local/lib/python3.* chmod 0755 ~/.local/lib/python3.*/site-packages
Run MousikóFídi like this:
sudo su - fidi mousikofidi --dev
The first time you run MousikóFídi, a config file will be generated at
$HOME/.config/fidi/config.toml. 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:
sudo su - fidi vi ~/.config/fidi/config.toml
See the Config Guide as well as the User's Guide for more information.
If running on your local machine, at this point you may open
http://127.0.0.1:5000/ in a browser to use MousikóFídi.
Read on for information about how to run MousikóFídi in production mode.
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 https://git.sr.ht/~hristoast/mousikofidi/blob/master/mousikofidi/example/uwsgi.ini
socket values should be changed to use
/opt/fidi/tmp instead of
/tmp/, see the example below as a reference:
[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
This can be done quickly with
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
Create that directory:
sudo su - fidi mkdir ~/tmp
MousikóFídi can now be ran via
uwsgi and the
sudo su - fidi mousikofidi --processes $(nproc)
Read on for how to access this via the Nginx HTTP server.
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
uwsgi is ran as specified above it will fork into the background. The specified log can be watched to see requests, errors, and etc.
This section requires superuser access to install the MousikóFídi Nginx configuration and enable it, as well as to install Nginx itself.
The user that
nginx is running as on your system will need read and write access to the socket created by running
sudo usermod -a -G fidi www-data
www-data above is the user that the
nginx server is running as.
Now, make sure that the
fidi group can access
sudo chmod 0750 /opt/fidi sudo chmod 0750 /opt/fidi/tmp
Read on for a description of how to configure Nginx to read the
Included with MousikóFídi is an example Nginx configuration file that you may use as a base for your own setup.
Copy this file to where nginx configs are kept:
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/
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:
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
sudo su - fidi mkdir ~/logs
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
sudo su - fidi ls -d ~/.local/lib/python3.*/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.
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:
certbot --dry-run certonly --nginx -w /opt/fidi/ssl --agree-tos -d mousikofidi.mycooldomain.tld
mousikofidi.mycooldomain.tld with your actual configured
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.
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.
cat > /etc/sv/fidi/log/run <<EOF #!/bin/sh exec logger -t mousikofidi EOF
runscript for MousikóFídi itself:
cat > /etc/sv/fidi/run <<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>&1 EOF
dscript for stopping MousikóFídi:
cat > /etc/sv/fidi/control/d <<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>&1 EOF
rscript for reloading/restarting MousikóFídi:
cat > /etc/sv/fidi/control/r <<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>&1 EOF
ln -sv /etc/sv/fidi /var/service/ # Or wherever the service dir is on your system, if not /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
supervisepermissions so the
fidiuser 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
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
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.
The MousikóFídi repo includes a sample unit file that can be used with systemd to run the application as a service.
Download the example file and run it as a user service:
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