Warning

This documentation only applies for the development version of Funkwhale! Visit the docs for the latest release.

Customize the Funkwhale frontend

You can customize the look and behavior of the Funkwhale UI using a JSON configuration file. This file enables you to make very basic changes to the Funkwhale web app.

Set up your custom configuration

Create your configuration file

To customize your Funkwhale pod, you need to serve a settings.json file at https://yourinstanceurl/settings.json. Follow these steps to set up your configuration file:

  1. SSH into your Funkwhale server.

  2. Navigate to your /srv/funkwhale folder

    cd /srv/funkwhale
    
  3. Create a new custom directory for your file.

    mkdir custom
    
  4. Create a new config file and populate it with placeholder settings.

    cat <<EOF > custom/settings.json
    {
    "additionalStylesheets": [],
    "defaultServerUrl": null
    }
    EOF
    
    Supported parameters

    Parameter

    Data type

    Description

    Example

    additionalStylesheets

    Array

    A list of URLs (relative or absolute) pointing to stylesheets.

    ["https://test/theme.css"]

    defaultServerUrl

    URL

    The URL of the API server you want to connect the frontend to. Defaults to the current domain.

    "https://api.yourdomain.com"

Configure your reverse proxy

Once you’ve created your settings.json file you need to configure your reverse proxy to serve it.

Add the following snippet to your /etc/nginx/sites-available/funkwhale.conf config file:

location /settings.json {
   alias /srv/funkwhale/custom;
}

Add the following snippet to your webserver configuration:

Alias /settings.json /srv/funkwhale/custom/settings.json

Reload your webserver. You should be able to see the contents of your configuration file at https://yourinstanceurl/settings.json.

Add a custom theme

You can use a custom stylesheet to theme your Funkwhale pod. To do this:

  1. Navigate to your /srv/funkwhale/custom directory.

    cd /srv/funkwhale/custom
    
  2. Copy your CSS file to this directory, or create a new one.

    # A basic CSS file. Turns the pod's background red.
    
    cat <<EOF > custom.css
    body {
    background-color: red;
    }
    EOF
    
  3. Add the location of your CSS file to the additionalStylesheets parameter in your settings.json file.

    nano settings.json
    
    # Add ["/front/custom/custom.css"] to the additionalStylesheets parameter
    # The resulting file looks like this:
    # {
    #   "additionalStylesheets": ["/front/custom/custom.css"],
    #   "defaultServerUrl": null
    # }
    
  4. Add the whole custom dir to your webserver configuration.

    Add the following to your /etc/nginx/sites-available/funkwhale.conf file:

    location /custom {
       alias /srv/funkwhale/custom;
    }
    

    Add the following to your webserver configuration file.

    Alias /custom /srv/funkwhale/custom
    
    <Directory "/srv/funkwhale/custom">
    Options FollowSymLinks
    AllowOverride None
    Require all granted
    </Directory>
    
  5. Restart your webserver.

Refresh your Funkwhale app. The background should now be red.