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.

Nginx

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

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

Apache

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.

   Nginx

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

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

   Apache

   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.