Funkwhale

Related articles
Django
Apache HTTP Server
Nginx
OpenSSL
Certbot
Redis
PostgreSQL
Quoting the
main documentation page
:
Funkwhale
is a self-hosted, modern, free and open-source music server, heavily inspired by Grooveshark.
Instances can be federated via the ActivityPub protocol.
Installation
Funkwhale requires a reverse proxy (
[1]
),
so
nginx
or
Apache HTTP Server
need to be installed.
It also needs a configured
PostgreSQL
database and a
Redis
cache server.
See
#Configuration
and the respective pages for information.
Install
the
funkwhale-venv
AUR
package.
Manual install
Follow instructions at
[2]
.
This will install all components in
/srv/funkwhale
.
Docker install
Follow instructions at
[3]
.
Configuration
The following sections assume
funkwhale-venv
was installed,
for a manual installation the folders should be changed appropriately.
It also assumes that you are using Funkwhale on a local network.
See the official
documentation
for making it accessible outside,
especially for the certificates using
Certbot
.
Host config
Make sure your
/etc/hosts
file is setup correctly.
The Funkwhale server is running on
127.0.0.1
with alias
funkwhale.local
, but this can be changed.
Your
/etc/hosts
file should look something like the following,
#<ip-address>   <hostname.domain.org>   <hostname>
127.0.0.1       localhost
::1             localhost
127.0.0.1       funkwhale.local
Configure nginx
The upstream template of the Nginx configuration file is provided in
/etc/webapps/funkwhale/nginx.template
.
However, this file contains variables that need to be replaced by their value from the
env
file
(see section
#Initialization
on how to create this file):
$ set -a && source /srv/funkwhale/config/env && set +a
$ envsubst "`env | awk -F = '{printf \" $%s\", $$1}'`" \
   < /etc/webapps/funkwhale/nginx.template \
   > /etc/nginx/sites-available/funkwhale.conf
The paths to the certificates should also be modified accordingly.
Then enable the site:
$ ln -s /etc/nginx/sites-available/funkwhale.conf /etc/nginx/sites-enabled/
And
start
the
nginx.service
.
Configure apache
Note
You will need
Apache HTTP Server
configured to run with
Redis
,
PostgreSQL
and Apache
TLS
support.
A template Apache configuration file is provided in
/etc/webapps/funkwhale/apache-funkwhale.conf
. It configures the Funkwhale instance to be accessible at
https://funkwhale.local
.
The folder names should be change to fit your installation. More explanation on which lines need to be modified is provided in
[4]
.
Copy the template to the apache configuration folder,
$ cp /etc/webapps/funkwhale/apache-funkwhale.conf /etc/httpd/conf/extra/funkwhale.conf
Next, edit the
Apache HTTP Server
configuration file and add the following:
/etc/httpd/conf/httpd.conf
Include conf/extra/funkwhale.conf
For the changes to be applied, you need to
restart
httpd.service
(Apache).
Configure PostgreSQL
Connect to the
PostgreSQL
command line using the
postgres
user to create the
funkwhale
user and the database.
[postgres]$ psql
CREATE DATABASE "funkwhale"
 WITH ENCODING 'utf8';
CREATE USER funkwhale;
ALTER DATABASE funkwhale OWNER TO funkwhale;
\c funkwhale;
CREATE EXTENSION "unaccent";
CREATE EXTENSION "citext";
The last three lines load the
unaccent
and
citext
extensions,
which are needed for funkwhale to work (
citext
since version 0.20).
Initialization
Funkwhale user
Funkwhale should run as the
funkwhale
user. It is automatically created by the AUR package.
If you followed the manual installation, create it with
# useradd -r -d /srv/funkwhale -m funkwhale -c "Funkwhale music server" -s /usr/bin/nologin
Create Funkwhale's data folders in
/srv/funkwhale
,
owned by the
funkwhale
user:
# mkdir /srv/funkwhale
# chown funkwhale:funkwhale /srv/funkwhale
Run the following commands as the
funkwhale
user.
Create sub-folders for API files and storage:
[funkwhale]$ cd /srv/funkwhale
[funkwhale]$ mkdir -p api data/static data/media data/music config
To work, Funkwhale needs several environment variables to be present, these should be defined in the environment file
/srv/funkwhale/config/env
.
There is a template at
/etc/webapps/funkwhale/env.template
, copy and modify it to fit your installation.
[funkwhale]$ cp /etc/webapps/funkwhale/env.template /srv/funkwhale/config/env
The
FUNKWHALE_HOSTNAME
variable should correspond to the hostname in
/etc/hosts
.
DJANGO_ALLOWED_HOSTS
needs also to match the address where the funkwhale instance will be reached.
You should generate a unique
DJANGO_SECRET_KEY
and change the paths accordingly to your installation.
Tip
As you will need to run several commands as the
funkwhale
user with the environment variables loaded, you can use the following command-line after logging in:
[funkwhale]$ export $(grep -v ^#  /srv/funkwhale/config/env | xargs)
For convenience, you can copy this line to
/srv/funkwhale/.bashrc
(or whichever shell you are using), so it is loaded automatically every time you log in to the funkwhale user.
Database setup
Use
/usr/bin/funkwhale_manage
to run the
/usr/share/webapps/funkwhale/api/manage.py
command as
funkwhale
user.
Initialize the database before launching the application:
[funkwhale]$ funkwhale_manage migrate
Create a superuser for your Funkwhale instance:
[funkwhale]$ funkwhale_manage createsuperuser
Collect the static files for the webapp:
[funkwhale]$ funkwhale_manage collectstatic
Note
If you do not use
funkwhale_manage
, you need to first activate the python virtualenv and then run the commands as the
funkwhale
user.
[funkwhale]$ source /usr/share/webapps/funkwhale/virtualenv/bin/activate
[funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py migrate
[funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py createsuperuser
[funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py collectstatic
[funkwhale]$ deactivate
Version upgrade
In case of an error, use the
/usr/bin/funkwhale_manage
script to run the
/usr/share/webapps/funkwhale/api/manage.py
commands (it should be run as root).
Warning
Check that the Apache or nginx configuration file did not change before restarting the service. Consult the official documentation for incompatible changes.
Usage
Upstream provides systemd services that are already installed.
To start the instance, just
start
funkwhale.target
.
This starts three services, you can check their status with:
$ systemctl status funkwhale-\*
Note
Before version 1.3.0, the AUR package used
funkwhale.service
, after it uses
funkwhale.target
like upstream.
Troubleshooting
See
https://docs.funkwhale.audio/administrator/troubleshooting/index.html
Proxy logs
Apache logs for funkwhale:
$ tail -f /var/log/httpd/funkwhale/error.log