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.

Install the funkwhale-venvAUR 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

Categories:

- Media servers
- Music
- Web applications

Funkwhale
Add topic