Funkwhale - ArchWiki

Jump to content

# Funkwhale

From ArchWiki

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.

### Installation from AUR

Install the funkwhaleAUR package.

Warning: This installation does not use a python virtualenv, so all the python dependencies are installed system-wide, mainly from the AUR. Package versions may differ from the upstream requirements and cause problems.

### Manual install

Follow instructions for the Arch installation at [2]. This will install all components in `/srv/funkwhale`.

### Docker install

Follow instructions for the Docker installation at [3].

## Configuration

The following sections assume that Funkwhale was installed from AUR, 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.conf \
       > /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) using systemd.

### Configure PostgreSQL

Here we follow the official documentation: [5]

Connect to the PostgreSQL command line using the `postgres` user to create the `funkwhale` user and the database.

    $ sudo -u postgres psql

    CREATE DATABASE "funkwhale"
     WITH ENCODING 'utf8';
    CREATE USER funkwhale;
    GRANT ALL PRIVILEGES ON DATABASE funkwhale 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 be 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 /sbin/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.

    $ sudo -u funkwhale -H bash

    [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 $(cat /srv/funkwhale/config/env | grep -v ^# | xargs)`

For convenience, you can copy this line to /srv/funkwhale/.bashrc (or whichever shell you are using), so it is loaded automatically everytime you log in to the funkwhale user.

### Database setup

Initialize the database before launching the application:

    $ sudo -u funkwhale -H bash

    [funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py migrate

Create a superuser for your Funkwhale instance:

    [funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py createsuperuser

Collect the static files for the webapp:

    [funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py collectstatic

Note: Starting with version 0.21, an alias is provided for `/usr/share/webapps/funkwhale/api/manage.py` in `/usr/bin/funkwhale_manage`, so you can instead use:

    [funkwhale]$ funkwhale_manage collectstatic

## Version upgrade

Note: Starting with version 0.21, an alias is provided for `/usr/share/webapps/funkwhale/api/manage.py` in `/usr/bin/funkwhale_manage`, so you can use:

    [funkwhale]$ funkwhale_manage [commands...]

instead of

    [funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py [commands...]

All commands should be entered as `funkwhale` user. Stop the `funkwhale.service` before upgrading.

The static files have to be collected again:

    [funkwhale]$ funkwhale_manage collectstatic --no-input

Apply database migrations:

    [funkwhale]$ funkwhale_manage migrate

To upgrade to version 1.0, the thumbnails quality has been increased from 70 to 95, so all the thumbnails should be regenerated (or set THUMBNAIL_JPEG_RESIZE_QUALITY=70 in the .env file so nothing changes). First delete the `__sized__ directory` in your `MEDIA_ROOT` directory, then regenerate the thumbnails,

    [funkwhale]$ rm -rf /srv/funkwhale/data/media/__sized__
    [funkwhale]$ funkwhale_manage fw media generate-thumbnails

Starting from version 0.20.1, there is a new `MUSIC_USE_DENORMALIZATION` parameter in the `env` file set to `True` (you can set it to `False` so nothing changes). It is a performance enhancement and to make it work you need to run the following command,

    [funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py rebuild_music_permissions

Warning: Check that the apache or nginx configuration file did not change before restarting the service. Consult the official documentation for incompatible changes.
Warning: From version 0.20, python-daphneAUR was replaced by uvicorn/gunicorn. The service file was updated not to use python-daphneAUR anymore. This can be changed by editing the `funkwhale-server.service` file.

Also, the `citext` extension for postgresql is now needed. It can be loaded with issueing the following command before calling the `migrate` command:

    $ sudo -u postgres psql funkwhale -c 'CREATE EXTENSION "citext";'

After completing all these steps, the `funkwhale.service` can be started again.

Note: All the instructions for upgrading are given on the official documentation [6].

## Usage

Upstream provides systemd services that are already installed with the AUR package.

To start the instance, just start `funkwhale.service`.

This starts three services, you can check their status with:

    $ systemctl status funkwhale-\*

## Troubleshooting

See https://docs.funkwhale.audio/admin/troubleshooting.html

### Proxy logs

Apache logs for funkwhale:

    $ tail -f /var/log/httpd/funkwhale/error.log

Categories:

- Media servers
- Music
- Web applications