# Funkwhale

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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.template`. 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 | 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.

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

    [funkwhale]$ funkwhale_manage [commands...]

instead of

    [funkwhale]$ python /usr/share/webapps/funkwhale/api/manage.py [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]$ funkwhale_manage collectstatic --no-input

Then 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 need to 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 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 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";'

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