Funkwhale - ArchWiki

# Funkwhale

From ArchWiki
Jump to navigation Jump to search

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 with the ActivityPub protocol.

## Installation

Funkwhale requires a reverse proxy ([1]), so nginx or Apache HTTP Server needs 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, mainly from the AUR. Package versions may be different from the upstream requirements and cause problem.

### Manual install

Follow instructions for the Arch installation at [2]. This will install all the 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.conf`. However this file contains variables that need to be replaced by their value from the `env` file (see in section #Initialization 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

    postgres=# CREATE DATABASE "funkwhale"
    postgres=#  WITH ENCODING 'utf8';
    postgres=# CREATE USER funkwhale;
    postgres=# GRANT ALL PRIVILEGES ON DATABASE funkwhale TO funkwhale;
    postgres=# \c funkwhale;
    postgres=# CREATE EXTENSION "unaccent";
    postgres=# CREATE EXTENSION "citext";

The last three lines load the `unaccent` and `citext` extensions, which are needed for funkwhale to work (`citext` for version >0.20).

### Configure Redis

There is no particular configuration for Redis.

## Initialization

### Setup

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"

Next, the folder where Funkwhale will store the users data should be created in `/srv/funkwhale`. It should be owned by the `funkwhale` user,

    $ mkdir /srv/funkwhale
    $ chown funkwhale:funkwhale /srv/funkwhale

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 it and modify it to fit your installation.

    $ mkdir /srv/funkwhale/config
    $ cp /etc/webapps/funkwhale/env.template /srv/funkwhale/config/env
    $ chown -R funkwhale:funkwhale /srv/funkwhale/config

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.

#### Log in as funkwhale user

The next commands should be run as the `funkwhale` user. Create sub-folders for api files and to store the music,

    $ sudo -u funkwhale -H bash

    [funkwhale]$ cd /srv/funkwhale
    [funkwhale]$ mkdir -p api data/static data/media data/music

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`

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.

### Database setup

You need to initialize the database before launching the application,

    $ sudo -u funkwhale -H bash

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

Then create a superuser for your Funkwhale instance,

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

You also need to 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 one can run instead:

    [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 one can run instead:

    [funkwhale]$ funkwhale_manage [commands...]

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

The static files have to be collected again,

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

Then apply database migrations,

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

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's 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 uvicornAUR/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";'

When all the upgrade steps were run, 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 by 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

### Proxy logs

Apache logs for funkwhale are available,

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

Categories:

- Media servers
- Music
- Web applications